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

The description adds behavioral context beyond annotations by stating the result is read-only and that the query should describe the intended task. It reinforces the readOnlyHint and clarifies the intended comparison workflow without contradicting the annotations.

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

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

The description is concise and front-loaded: the first sentence states the purpose, and the second adds usage and read-only context. No filler or redundant explanation is present.

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-only search tool with an output schema and annotations, the description covers when to use it, what the query should contain, and the read-only nature. The only minor gap is the unmentioned limit parameter, but the schema provides enough information for a competent agent.

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 the meaning of query ("should describe the intended task") but does not mention limit or its effect on result count. Limit semantics are left to inference from the schema's name and default value.

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

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

The description opens with a specific verb and resource: "Find open threads that may overlap a planned task." It clearly distinguishes this from sibling tools like list_open_threads by focusing on overlap detection against a planned task, not just listing threads.

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

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

It explicitly says "Use before starting potentially new work" and advises comparing matches before creating another thread. It does not name sibling alternatives or describe when not to use the tool, but the primary usage 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 key side effects: 'Quiets the “still relevant?” prompt via reminder cooldown' and explicitly states what it does not do ('does not change status and never dismisses'). It does not mention error behavior or return format, but the output schema exists, and the side effects are adequately described.

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, front-loaded with the core purpose, and then efficiently covers exclusions and alternatives. No wasted words; every sentence adds value.

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 single-parameter tool with an output schema, the description covers purpose, side effects, and alternatives. It does not explain the parameter semantics or error conditions, but given the simplicity and available schema, it is nearly complete.

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

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

Schema description coverage is 0%, so the description must compensate. It never mentions thread_id, leaving its purpose and format implicit. The tool name and description imply it identifies the stale open thread, but the description does not explicitly explain the parameter, which is a gap given zero schema 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 a specific action ('Confirm') on a specific resource ('a stale open thread') and places it in context ('Wave 7 soft triage'). It also clearly differentiates from siblings by stating what it does not do ('does not change status and never dismisses').

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 names alternatives and their conditions: 'Use snooze_thread_triage to ask again later, or dismiss_thread only when the human intentionally abandons it.' This gives clear when-to-use guidance and when not to use this tool.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It does well by explicitly stating that deletion is not immediate, that the action is queued for human confirmation, and that the flags only describe what a confirmed action will remove. It does not cover permissions, idempotency, or post-confirmation behavior, but the most critical non-obvious behavior is clearly disclosed.

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 core action, and each sentence adds value: the queue behavior, the non-immediate nature, the purpose of flags, and the inspection workflow. There is 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?

For a deletion-queueing tool with an output schema available, the description is largely complete: it states the action, the confirmation step, and how to inspect pending requests. The main gap is the lack of per-flag parameter explanation, which is important for correct invocation, but the overall workflow context is strong enough to make the tool usable.

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 references 'flags' generically but never explains what delete_remote or delete_progress actually control, nor does it describe the purpose of reason. The parameter names and defaults offer some hints, but an agent cannot reliably understand the semantics of each flag 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 opens with a specific verb+resource+context: 'Queue project deletion for human confirmation in /ui.' This clearly distinguishes it from direct or immediate project actions like resolve_project or rename_projectchers. The added detail that nothing is deleted immediately further sharpens the intended action.

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 about when to use this tool: to queue a deletion that requires human confirmation. It also routes the agent to list_pending_actions for inspecting the queued request before confirmation. However, it does not explicitly state when not to use this tool or mention alternatives for direct deletion, so it misses the full 5.

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

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

No annotations are provided, so the description carries full behavioral burden. It conveys the core behavior (soft-close without marking complete) and distinguishes it from mark_done and pause_thread, but it does not disclose potential side effects like visibility changes, notifications, or reversibility. The description adds some context but lacks deeper behavioral detail expected for a mutation 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?

Two sentences with zero fluff. The core purpose is front-loaded, and usage guidance is tightly packed. Every sentence earns its place, and the structure reads naturally.

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

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

The output schema exists, so return values are covered. The description handles purpose and usage well, but given no annotations and 0% parameter coverage, it misses important details about parameter meaning and side effects. For a tool with only 2 parameters, this is a moderate gap, but the description is still functional.

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

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

Schema description coverage is 0% and the description does not mention either parameter (thread_id or note). The agent only has the schema's property definitions, which are minimal (just type and title). The description fails to compensate for the lack of schema documentation, leaving parameter semantics under-specified.

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 starts with a specific verb and resource: 'Soft-close a thread' and immediately defines the meaning ('stop without being marked complete'). It also explicitly names sibling tools (mark_done, pause_thread, confirm_thread_relevant, snooze_thread_triage) and distinguishes its purpose from each, making it 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?

Provides explicit when-to-use conditions ('abandoned, superseded, or no-longer-relevant work') and when-not-to-use alternatives ('Use mark_done when the intended outcome was completed, or pause_thread when it will be resumed later'). It even warns against auto-dismissing from the stale-work check tools, giving clear routing.

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

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

Annotations already declare readOnlyHint=true, so the description's 'read-only' is redundant but consistent. It adds value by disclosing the output scope (counts, next-up work, due reminders) and the compact nature, which goes beyond the structured annotation.

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 concise sentences, front-loaded with the core purpose and immediately followed by the alternative usage. No filler or repetition, every sentence earns its place.

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

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

Given the tool is a read-only overview with no parameters and an output schema exists, the description fully covers what an agent needs to know: what it returns and when to use it instead of a sibling. Nothing essential is missing.

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

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

Tool has zero parameters, so the description is not required to explain any. The baseline for no parameters is 4, and the description correctly avoids unnecessary param 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?

Description clearly states a specific action (return) and resource (compact, read-only Hub overview), and explicitly lists its contents (counts, next-up work, due reminders). It also names the sibling session_digest, making differentiation straightforward.

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 guidance on when to use this tool versus the alternative: 'Use session_digest when you also need project-specific resume context or the progress wiki snippet.' This directly tells the agent the selection 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 already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context such as 'without changing them' (aligning with readOnlyHint) and characterizes the output as a 'raw thread list.' It does not detail pagination or return format, but since an output schema exists, that information is available elsewhere. The description complements annotations without redundancy or contradiction.

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 exactly two sentences, front-loading the primary purpose and then providing usage nuance. Every clause earns its place: the read-only guarantee, the filtering hint, and the explicit alternative to session_digest. No redundancy or padding.

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

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

For a read‑only list tool with three optional parameters and an output schema, the description covers the essentials: what it lists, that it is non‑destructive, when to use it, and when to prefer an alternative. It omits nitty‑gritty details like default limit or pagination, but those are covered by the schema and the output schema. The presence of the output schema lowers the burden, making this reasonably complete.

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

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

Schema description coverage is 0%, so the description must clarify parameters. It explicitly mentions filtering by 'project' and 'energy,' which correspond to project_slug and energy, but does not explain the limit parameter or the format of project_slug. Since limit is self-explanatory and energy has an enum, this partial coverage is adequate but not complete. The description adds some meaning beyond the schema's bare titles, but leaves the limit unaddressed.

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 clear verb and resource: 'List unfinished threads without changing them.' It specifies the exact scope (unfinished threads) and reinforces read-only behavior, which distinguishes it from mutation siblings like pause_thread or dismiss_thread. The mention of 'raw thread list' further clarifies the nature of the output, leaving no ambiguity about what the tool does.

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 provides when to use this tool vs. an alternative: 'Use session_digest when you want a session-start summary with reminders and resume context instead of the raw thread list.' It also advises filtering by project or energy for narrowing work, giving clear situational guidance. This is a model of usage direction.

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

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

The description reinforces the readOnlyHint by stating it is read-only and adds context about pending confirmation workflow state. This goes beyond the annotation by explaining that it surfaces actions awaiting confirmation after a rename or delete.

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 concise sentences front-load the core purpose and immediately follow with the operational context. No wasted words or redundant detail.

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

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

With no parameters, a readOnlyHint annotation, and an output schema present, the description covers everything needed for correct invocation. The post-mutation use case completes the operational picture.

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 there is nothing the description needs to clarify beyond what the schema already shows. Baseline for zero parameters is satisfied.

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 a specific resource ('project rename/delete requests waiting for /ui confirmation'). This clearly distinguishes the tool from siblings like get_overview, list_projects, and list_open_threads.

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 states this is useful after rename_project or delete_project, giving clear context for when to use it. It does not list exclusions or alternative tools, but the intended use case is evident.

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

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

Annotations already declare readOnlyHint: true, and the description reinforces that with 'This is read-only', which is somewhat redundant. However, it adds useful behavioral context beyond annotations by stating the return content ('open/done thread counts') and the intended use case. It does not detail ordering, pagination, or error behavior, but given the read-only safety is already covered, this is a minor gap.

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

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

The description is exceptionally concise: two sentences with zero filler. The primary action is front-loaded ('List registered Hub projects...'), followed by usage guidance and alternatives. Every sentence earns its place, and the structure is efficient and scannable.

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

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

The description is complete for a read-only list tool: it states what it does, when to use it, and which sibling tools are appropriate for other operations. Since an output schema exists, return values need not be explained. The description could mention the limit parameter or ordering, but those are minor given the tool's simplicity and the presence of schema constraints.

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% description coverage, and the description does not mention the 'limit' parameter at all. As the only parameter, 'limit' is self-explanatory given its integer type, default (100), min (1), and max (500). The schema provides sufficient constraints, but the description's lack of any mention means it does not compensate for the low coverage. Since the parameter is straightforward, this is acceptable but not ideal.

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'), the resource ('registered Hub projects'), and the output content ('open/done thread counts'). It also distinguishes itself from sibling tools by explicitly naming 'resolve_project' and 'upsert_project' as the alternatives when a project needs resolution or change, so an agent can easily select the right tool without ambiguity.

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

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

The description provides explicit when-to-use guidance ('Use for project discovery or navigation') and explicit when-not-to-use guidance by stating it is read-only and directing the agent to 'resolve_project or upsert_project' for modification tasks. This leaves no ambiguity about situational appropriateness.

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

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

The 'without changing them' statement aligns with and reinforces the readOnlyHint annotation. It adds the 'persisted' qualifier but does not disclose much beyond what annotations already provide; this is acceptable since annotations cover 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?

The description is concise and the core purpose is front-loaded in the first sentence, with parameter guidance following. Minor indentation whitespace is present but does not impede readability.

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

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

Given the two simple boolean parameters, a readOnly annotation, and an existing output schema that can document return values, the description covers the essential usage decisions. It is sufficiently complete for an agent to invoke the tool correctly.

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

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

Schema description coverage is 0%, but the description compensates by explaining due_only as surfacing reminders needing attention now and include_handled as relevant only for historical handled reminders. This adds meaning that the bare boolean schemas lack.

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 ('List') and a precise resource ('persisted Hub reminders'), and explicitly notes the operation does not change them. This clearly distinguishes it from mutation-oriented siblings like set_reminder.

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 guidance on when to set due_only=true ('at session start') and when include_handled=true is appropriate ('only when historical handled reminders are relevant'). Though it does not name alternative tools, the guidance clearly frames the intended use context.

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

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

There are no annotations, so the description carries the behavioral burden. It communicates that this is a finalization action for completed work and that note is optional, but it does not disclose whether closing is irreversible, requires permissions, or what side effects occur on the thread state. Sibling contrast with pause_thread implies terminality without making consequences explicit.

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 concise sentences, each earning its place: the core action, the usage conditions with named alternatives, and the optional parameter note. Front-loaded with the primary action before routing details.

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

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

For a simple two-parameter finalizer, the description covers when to call, what precondition must be met, alternatives, and parameter note semantics. Missing explicit behavioral consequences like reversibility are a small gap, but the output schema exists and operation scope is simple enough that the definition is largely complete.

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

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

Schema description coverage is 0%, so the description must compensate. It adds that thread_id must be 'known' and that note is an 'optional completion note, but it does not add meaningful constraints like where thread_id comes from or how note is stored. Coverage is minimal but minimally adequate for two simple parameters.

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

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

States a specific verb ('Close') and resource ('a specific thread') plus the completion condition ('when its finishable outcome is complete'). It distinguishes itself from pause_thread and dismiss_thread by naming them as different intent paths, so an agent can tell this tool apart from 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?

Gives explicit guidance on when to use this tool and when not to, including named alternatives and their conditions: pause_thread for unfinished work and dismiss_thread for intentional abandonment. This is model-level routing guidance that goes beyond the schema.

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 behavioral burden. It transparently states that the tool updates pause/resume state, which is the core side effect an agent needs to know. It does not discuss failure behavior or idempotency, but for a simple state-update tool this disclosure is mostly adequate.

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 focused sentences front-load the primary purpose, then provide usage context, alternatives, and required inputs. There is 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?

With an output schema present, return-value documentation is not required. The description covers purpose, when to use, alternatives, and parameter roles for a simple two-parameter tool, leaving little critical information missing for correct invocation.

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

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

The input schema has 0% description coverage, so the description must compensate. It adds meaning by describing next_step as a 'concrete next action to resume' and requiring an exact thread_id, but it doesn't define thread_id beyond its name or address error cases. It partially compensates but leaves some semantic detail to inference.

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

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

The description uses a specific verb and resource ('pause thread') and clearly states it saves a concrete next action. It also distinguishes itself from mark_done and dismiss_thread, which are named explicitly as alternatives. This makes the tool's unique role 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 gives an explicit when-to-use condition ('Use when the thread will continue later') and names the alternatives for completed vs abandoned work. It also states the precondition 'Requires the exact thread_id and next_step'. This fully guides selection and invocation.

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

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

The description discloses that the operation has an external side effect, is best-effort, and depends on integration configuration. However, with no annotations at all, it leaves unspecified what happens if the integration is missing, whether the push can overwrite previous memory, or whether the operation 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?

The description is front-loaded with the core action and stays compact at three sentences. 'Short Hub digest' and 'compact Hub-generated digest' are slightly redundant, but the overall structure is easy to scan.

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

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

The tool is simple with two optional parameters and an output schema, so return-value documentation is not necessary. The description covers the operation's purpose, content type, prerequisite integration, side effect, and parameter roles. The main remaining gap is failure behavior when the integration is not configured.

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?

Since schema coverage is 0% and no annotations exist, the description carries the burden of explaining the two parameters. It does so by saying project_slug narrows the digest and note adds short context, which adds real meaning beyond the bare schema. It could specify accepted formats or requiredness more explicitly, but the semantic roles are clear.

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 states a specific action ('push'), a target ('configured OpenClaw memory'), and a content constraint ('short Hub digest'). It also explicitly rules out raw chats, which helps distinguish it from potential sibling tools like session_digest or memory-write tools.

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

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

The description gives clear context: this is for compact Hub-generated digests, not raw chats, and it requires the operator's OpenClaw integration to be configured. It does not name specific alternatives or articulate explicit when-not-to-use cases beyond raw chats, but the usage context is sufficiently 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?

No annotations are present, so the description carries the burden. It explicitly discloses the side effect of persisting the mapping and the conditional thread creation tied to create_open_thread. It could add specifics about idempotency or error cases, but the main behavioral implications are disclosed.

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

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

Three sentences, each with a clear role: purpose, side effect, and alternative. No filler.

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

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

For a registration tool with an output schema, it covers the core action, side effects, and key alternative, and it mentions the one behavior-affecting parameter. It could be more complete by noting whether registration overwrites existing mappings or requires path validation, but these are not critical gaps.

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

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

Schema description coverage is 0%, so the description must compensate, but it only explains create_open_thread's conditional behavior. workspace_path, title, summary, and source_tool receive no semantic explanation.

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 ('Register') and resource ('local folder as a Hub project') and clarifies that this is a single combined operation. It distinguishes itself from resolve_project by emphasizing registration and persistence.

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

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

Explicitly says to use resolve_project when only resolution or lookup-with-create is needed, making the boundary between the two tools clear. It also implies this tool is for cases where the workspace/project mapping must be persisted.

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 transparently discloses that the action is queued, not immediate, and requires human confirmation, and points to where pending confirmations appear. It doesn't discuss permissions or reversibility, but for a queued operation, this level of disclosure is strong.

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 concise and front-loaded with the core purpose. It uses two short paragraphs with clear separation of the primary action and the important caveat about queued confirmations, with no wasted words.

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

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

Given four parameters with zero schema coverage and no output schema explanation (though one exists), the description leaves the agent without guidance on parameter specifics. It also omits any prerequisites, such as whether the project must exist or whether the new slug must follow a format. For a tool with this complexity, the description is 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?

Schema description coverage is 0%, and the description offers no explanation of the parameters (slug, new_slug, title, reason). While parameter names like 'new_slug' are somewhat self-explanatory, the description does not clarify required vs. optional semantics or format expectations, failing to compensate for the lack of schema descriptions.

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

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

The description clearly states the tool's action: 'Queue a project rename for human confirmation in /ui.' It specifies the verb (queue), the resource (project rename), and the target interface (/ui), making the tool's purpose unambiguous and distinct from siblings like upsert_project or delete_project.

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

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

It explicitly states when to use it: 'Use when the project identity should change.' It also provides a critical usage note that the rename is not applied immediately and directs to list_pending_actions for seeing queued confirmations, effectively giving both usage context and an alternative for checking status.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It does reveal an important nuance: the Hub cannot independently verify the client's state, so the tool records a client-supplied result. However, it does not mention whether this is a write/overwrite operation, whether it validates input, or what happens if called before verification.

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, purposeful sentences. The core purpose is front-loaded, the usage condition is immediate, and every sentence contributes meaning without redundant phrasing.

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

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

The description covers purpose and invocation timing, and the presence of an output schema partially compensates for return-value details. Still, an agent is left guessing how to populate source, project_slug, and workspace_path, and whether omitted version fields should be null or filled. It is usable but not fully self-contained.

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

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

Schema description coverage is 0% and the description does not explain any of the six parameters. The phrase 'versions of Hub guidance' loosely maps to the three version fields, but source, project_slug, workspace_path, and how defaults interact are left undefined. The property names are self-explanatory to a degree, but the description adds too little value for a 6-parameter tool.

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

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

The opening sentence 'Record versions of Hub guidance a local client actually verified' names a specific action and resource, and the scope is clearly limited to locally verified results. It also distinguishes this from other tools by emphasizing the client-side provenance, which no sibling description does.

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?

'Call only after the client itself inspected managed markers or ran a local doctor/setup check' is an explicit precondition, and the explanation that the Hub cannot inspect the client's checkout gives a strong rationale. It lacks a named alternative or an explicit when-not-to-use clause, but the usage context is unusually 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 full behavioral burden. It discloses the potentially mutating side effect ('may create a local project registry entry') and explains how to force read-only behavior. It does not mention error paths or permissions, which is a gap, but the key side effect is clearly stated.

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

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

The description is short, front-loaded with purpose, and every sentence adds value: usage timing, side effect control, and alternative tool. No fluff 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?

Output schema exists, covering return format, so that part is satisfied. The description covers usage timing, side effects, and alternatives, but omits the meaning of 'title', the precedence between path and slug, and failure behavior. For a tool with 0% schema coverage and no annotations, this leaves meaningful gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It explains workspace_path and project_slug as the resolution inputs, and create_if_missing with its effect. However, the 'title' parameter is not mentioned at all, and the precedence or exclusivity of workspace_path vs project_slug is not clarified. Partial coverage, but 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 begins with 'Resolve the current Hub project from a workspace path or slug' – a clear verb (resolve), resource (current Hub project), and the two input forms. It distinguishes itself from siblings by explicitly naming 'upsert_project' for metadata changes, so an agent can tell them apart.

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 usage timing ('Use at session start before session_digest'), clarifies the behavior of create_if_missing and its read-only counterpart, and points to upsert_project as the alternative for metadata changes. This is direct, unambiguous 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 behavioral disclosure burden. It explains what the digest combines, how query and energy alter output, that the Hub cannot inspect the client checkout, and that the guidance field depends on a local verification step. It stops short of explicitly stating whether the call has side effects, though the 'build/combine' framing strongly implies a read-only digest.

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 purpose in the first sentence, followed by composition/behavior and a focused caveat about the guidance object. Each section earns its place, and the organization makes it easy to skim; the doctor instructions add a little length but are functionally relevant.

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

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

The output schema exists, so return values need not be restated. The description covers the prerequisite, digest components, parameter effects for two inputs, and the guidance caveat. However, workspace_path is omitted entirely, and with no annotations the side-effect profile is left to inference, leaving a clear but not fatal completeness gap.

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

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

Schema description coverage is 0%, so the description must supply parameter meaning. It does for query ('narrows overlap relevance') and energy ('filter work to the operator's current capacity'), but workspace_path is never mentioned, and there is no explanation of null/default behavior. The two explained parameters add real value, but one of the three inputs is left 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?

Opens with a specific verb and resource — 'Build the session-start resume digest for the current work context' — and enumerates the digest's components (stale/open threads, due reminders, progress wiki snippet). This makes it readily distinguishable from sibling tools like list_open_threads, get_overview, or resolve_project without needing to inspect their schemas.

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

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

Explicitly states the sequencing prerequisite 'Use after resolve_project' and offers a concrete alternative path for making the guidance field meaningful via local doctor or report_guidance_health. It does not spell out when not to use this tool, but the guidance is clear and actionable.

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

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

No annotations are provided, so the description carries the full burden. It indicates mutation ('Create and persist') and explains scheduling behavior, but it does not disclose any side effects, permissions, or idempotency. For a create tool with zero annotation coverage, this is a moderate gap, though the persistence aspect is mentioned.

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 concise, with the main purpose front-loaded and parameter details following. Every sentence adds value, and there is no 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?

The tool has an output schema, so return details are covered. The description provides enough to call the tool correctly: it explains the main purpose, the key parameters, and points to the sibling for reading. Minor omissions like authentication or exact behavior on existing reminders are not critical given the simplicity and output schema.

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%, but the description adds meaning for two of three parameters: 'kind selects once, session, daily, or random scheduling' and 'due_at_iso is an ISO datetime used for a once reminder.' The 'message' parameter is not elaborated, but it is self-explanatory. The description compensates for the lack of schema documentation on key parameters.

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

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

The description clearly states the tool's purpose: 'Create and persist a Hub reminder.' It also specifies the scheduling kinds and distinguishes itself from list_reminders, which is a sibling that reads rather than creates.

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

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

It explicitly tells when to use this tool (to create) and when to use the alternative: 'Use list_reminders to read existing reminders without creating one.' This gives clear context and an alternative, fully covering usage 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 soft nature ('Soft only — thread stays open'), clarifies it does not auto-dismiss, and mentions the default 7 days. However, it does not state reversibility, idempotency, or any side effects beyond the snooze, but the core behavior is transparent enough for a mutation 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?

The description is compact (three sentences) with no filler. The purpose is front-loaded, followed by the critical 'soft only' caveat and then the alternative. Every sentence adds value and nothing is redundant.

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

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

Given the simple two-parameter schema and presence of an output schema, the description provides enough for an agent to invoke it correctly: it identifies the target (thread), the delay (days), and the behavioral constraint (soft, non-dismissing). It lacks explicit mention of prerequisites or side effects beyond the immediate action, but these are minor for a snooze 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?

The schema coverage is 0%, so the description must compensate. It mentions the default for days ('default 7') and implies thread identity via 'stale-thread', but it does not explicitly explain that thread_id is required or that days is optional with a 1-30 range. The description adds some context for days but leaves thread_id semantics implicit, so it partially compensates for the missing schema 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 uses a specific verb ('snooze') and names the resource ('stale-thread triage prompts'), clearly indicating a postponement action rather than a resolution. It explicitly contrasts with confirm_thread_relevant, naming the sibling and the condition that selects it, so an agent can distinguish this tool from alternatives without opening schemas.

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

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

It states when to use this tool ('when the outcome is still wanted now' is the condition for the alternative) and explicitly excludes auto-dismissal ('Never auto-dismisses'). It also provides an alternative tool name (confirm_thread_relevant) for immediate action, giving clear context for selection among siblings.

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

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

With no annotations, the description carries the behavioral disclosure burden. It discloses that this is a soft, non-destructive ranking tool that prefers quiet/stale open work and never starts or dismisses work. This gives the agent essential 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, followed by behavioral constraints and a usage cue. Minor rhetorical filler like 'Wave 7 continuity intelligence' does not significantly hurt clarity.

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

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

For a read-only suggestion tool with an output schema and no required parameters, the description covers purpose, usage context, and safety behavior well. It omits project_slug semantics and fallback behavior when no work matches, but these are not critical for safe 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 description adds meaning for energy ('optional energy match') and focus_project_slug ('honour focus mode / drift'), but project_slug is never mentioned and the energy enum values are not explained. Given 0% schema description coverage, this is partial compensation with a notable gap.

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

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

The description clearly identifies a specific verb ('pick'), a resource ('cross-project Next-up'), and a mode ('soft ranking only'). It also differentiates itself from action-taking siblings by explicitly stating it never starts or dismisses work.

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

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

The description explicitly says to prefer this tool when focus is off and the human asks 'what now?', and explains how focus_project_slug honors focus mode/drift. It does not name specific alternatives or exclusion conditions, but the intended 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 behavioral burden, and it does disclose key side effects: saving to PROGRESS.md, possibly creating a missing thread, and the ability to request a thread_id when selection is ambiguous. It does not mention overwrite/merge semantics or auth requirements, but the main behavioral risks are surfaced.

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 core purpose, then provides compact behavioral rules. It is somewhat dense with multiple directives in a few sentences, but every sentence adds operational value and there is no filler.

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

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

Given 13 optional parameters and no annotations, the description covers the important usage decisions: thread selection, content discipline, and thread-creation side effects. It does not explain every parameter or return behavior, but the output schema exists and the most consequential behavior is documented.

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

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

Schema description coverage is 0%, so the description must add meaning, and it does: thread_id is tied to avoiding wrong-thread checkpoints, content is reserved for rare meaningful events, force_new_thread and create_thread_if_missing are explained. Some parameters like project_slug, workspace_path, and source_tool are not addressed, but the most decision-critical ones are clarified.

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

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

The opening sentence, 'Save a checkpoint to active thread state and project PROGRESS.md', states a specific verb, resource, and destination. It is clear about what the tool does, and the mention of PROGRESS.md hints at its distinct role, though it does not explicitly name a sibling tool it differs from.

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 and when-not-to-use guidance: 'Prefer a known thread_id', 'Update structured Goal/Focus/Next/Blocked/Resume only on routine checkpoints', and 'Reserve content for rare human-meaningful events'. It also explains decision paths for ambiguous selection, force_new_thread, and create_thread_if_missing, giving an agent actionable routing rules.

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

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

With no annotations, the description carries the behavioral disclosure burden. It states this persists local Hub configuration, does not touch remote forge repositories, and rejects parent cycles. It could additionally explain whether unspecified fields are cleared or preserved on update, but the disclosed behavior is substantive.

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

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

Four focused sentences, front-loaded with the core purpose, followed by usage context and an important boundary. Every sentence adds value and there is no 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?

Given 11 parameters, no schema-level descriptions, and no annotations, the description is reasonably complete: it covers purpose, key parameter intent, side effects, and a critical non-goal. It could be more complete by directing the agent to sibling tools for rename or delete operations, but it is not missing essential call information.

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 groups parameters by category and adds real meaning for parent_slug via 'unlimited depth; cycles rejected,' but several parameters such as slug, description, forge_owner, forge_wiki_path, and forge_project_id are only vaguely bundled under 'forge targeting'.

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: 'Create or update a project registry entry and its explicit metadata.' It clearly lists the fields involved and explicitly distinguishes the tool from remote forge repository operations, so an agent can tell it apart from rename_project and delete_project.

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 an explicit 'Use when' clause covering the settable fields: title, workspace path, repository, energy, parent, and forge targeting. It does not name alternative sibling tools for local project management, but the remote/local distinction prevents obvious misuse.

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 present, so the description carries the full burden. It discloses the create-vs-update branching via thread_id and the domain rule that one thread equals one finishable outcome. However, it does not explain update merge/replace semantics, persistence side effects, or any auth/permission requirements.

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

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

The description is concise and front-loaded with the primary create/update purpose. The extra guidance about finishable outcomes and upsert_progress earns its place, though the formatting with indentation is slightly loose.

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 14-parameter upsert tool with no annotations and no schema descriptions, this description is too thin. It provides good routing and purpose, but an agent cannot confidently populate fields like goal, focus, chat_ref, transcript_ref, or source_tool based on this text. The output schema covers return shape, so that is not a gap, but field-level semantics remain unclear.

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 14 parameters with 0% description coverage, so the description must compensate. The only parameter given real meaning is thread_id ('Pass thread_id when updating a known thread'); the required summary field and most other fields receive no clarification.

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: 'Create a new finishable work thread or explicitly update one.' It clearly distinguishes the tool from siblings like upsert_progress and mark_done by defining a thread as a single finishable outcome.

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 to use this tool versus alternatives: 'For routine checkpoints on active work, prefer upsert_progress.' It also gives a concrete update condition: 'Pass thread_id when updating a known thread.'

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