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

With no annotations, the description carries full responsibility for disclosing behavior. It transparently states that the tool mutates state by auto-retrying, escalating, and releasing tasks, and it flags dry_run as a non-destructive preview mode. This is strong behavioral disclosure.

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

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

The description is about 35 words, front-loaded with the core scan-and-remediate behavior, and includes the key safety note about dry_run in a second sentence. Every sentence earns its place with no 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?

This is a simple tool with one optional parameter and no output schema. The description fully covers what the tool does, what actions it takes, and how to preview changes safely. Nothing essential for correct invocation is missing.

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

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

The input schema already documents dry_run with 100% coverage, so the description doesn't need to add much. It does reinforce the parameter's purpose by saying 'Use dry_run=true to preview actions without making changes,' but this is largely redundant with the schema description.

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

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

The description names a specific verb ('Scan') and resource ('overdue and failed tasks'), then spells out the concrete actions: auto-retry, escalate, release. This clearly distinguishes it from sibling task-management tools like update_task or complete_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 clearly establishes when to use the tool: when there are overdue, failed, exhausted, or timed-out tasks needing automated handling. It also recommends using dry_run=true to preview actions, providing a clear safety-first usage context, though it does not explicitly name alternatives or exclusion conditions.

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

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

With no annotations provided, the description carries the full disclosure burden and meets it: it reveals atomicity, the concrete mutation (status→claimed, assignee recorded), the concurrency failure mode (second claimer gets a clear error), and a precondition check (dependency completion). This is rich behavioral context well beyond a bare 'claim a task' statement.

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

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

Three tightly packed sentences front-load the core action first, then side effects, then failure and precondition behavior. Every sentence earns its place; the only minor redundancy is 'atomically' versus 'prevents race conditions', which is acceptable since the latter adds the concrete error outcome.

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 moderately complex concurrency-safe mutation tool, the description covers preconditions, side effects, and error behavior thoroughly, and the schema documents all parameters. The only gap is the absence of an output schema or any statement about the success response shape, which the description does not address.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the assignee parameter via 'records the assignee' but adds no meaning beyond what the schema already documents for task_id, worktree_path, or worktree_branch. It neither hurts nor materially enhances 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?

"Atomically claim a pending task for an agent" names a specific verb (claim), a specific resource (pending task), and an actor (agent), with the side effect spelled out (sets status to 'claimed', records assignee). The claim verb clearly differentiates it from lifecycle siblings like create_task, update_task, and complete_task without needing to open 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?

The description implies usage — an agent claims a pending task, and the dependency-completion check indicates a precondition. However, it never explicitly names alternatives or exclusions (e.g., use create_task to make a task, complete_task to finish one), so routing among the lifecycle siblings is left to inference.

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

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

With no annotations, the description carries the behavioral burden. It discloses important side effects: recording completed_at, appending to the Agent Log, linking deliverables, and auto-unblocking dependent tasks. It does not clarify whether unblocking applies to failed/cancelled statuses or discuss reversibility, but the core side effects are well covered.

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

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

The description is a single, well-structured sentence that leads with the core purpose and then enumerates side effects. No filler or redundant wording; every clause adds relevant context.

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, main parameters, and the most significant side effects in a compact form. The main gap is that 'automatically unblocks dependent tasks' is ambiguous for failed/cancelled statuses, and there is no output schema or annotation to fill in remaining behavior.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description mostly reinforces what the schema says (summary is appended to log, deliverables are linked), without materially adding new 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 opens with a specific verb and resource: 'Mark a task as completed (or failed/cancelled)'. It clearly identifies this as the terminal-status action and mentions the key side effects, which distinguishes it from siblings like update_task or claim_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 implies when to use the tool—when a task reaches a terminal state—but it does not explicitly contrast it with alternatives like update_task for non-terminal edits or claim_task for assignment. The context is clear, but exclusion guidance is missing.

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 must carry the behavioral transparency burden. It discloses the key behavioral traits: automatic parent folder creation, optional frontmatter, and the overwrite/failure policy. It does not mention return values or error details, but for a create-note operation the main side effects are well covered.

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 concise sentences with no filler. The primary action is front-loaded, and the edge cases (parent folders, failure-if-exists) are included 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?

With 100% schema coverage and no annotations or output schema, the description covers the essential elements: what the tool does, auto-created parent folders, and the overwrite behavior. It could mention the return value, but for this simple create operation the description is adequate for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, and the schema already explains path, content, overwrite, and frontmatter in detail. The description adds little beyond restating frontmatter and overwrite behavior, so it does not meaningfully enhance the parameter semantics.

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

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

The description clearly states the action: 'Create a new note in the vault' with optional YAML frontmatter. It also distinguishes this from siblings by emphasizing 'new' and the failure-if-exists behavior, which is different from update_note or delete_note.

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 clear context for when to use this tool: to create a new note, with parent folders created automatically, and it fails if the note already exists unless overwrite=true. It does not explicitly recommend update_note as an alternative for existing notes, so it falls short of fully explicit 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?

No annotations are provided, so the description carries the behavioral burden. It discloses useful behavioral details: independent tasks can be claimed in parallel, all task IDs are returned for immediate claiming, and append mode adds sub-tasks to an existing project. It does not discuss side effects like irreversibility or failure atomicity, but the main operational traits an agent needs are present.

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: five short sentences, with the core purpose front-loaded in the first sentence. Every sentence contributes either a usage pattern, a behavioral note, or append-mode guidance. 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?

The description covers the key operational aspects: bulk project creation, dependency wiring, parallel claiming, return of task IDs, and append mode. With 100% schema coverage of all parameters, the definition is nearly complete. It could have explicitly mentioned that title and description are required for new projects, but that information is already present in the 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 100%, so every parameter is already documented in the schema. The description reinforces depends_on_indices and project_id but does not add meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific action and resource: 'Create a project with multiple sub-tasks in one call.' It distinguishes itself from the sibling create_task by emphasizing bulk creation of multiple sub-tasks, so an agent can tell them apart without opening the schema.

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

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

The description gives clear usage context: use this tool for multi-sub-task projects, wire dependencies with depends_on_indices, and use append mode by passing project_id. It does not explicitly name create_task as the alternative, but the usage context is clear enough that an agent can decide when this tool is appropriate.

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

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

With no annotations, the description carries the behavioral disclosure burden. It discloses that the tool creates a markdown note, stores it in Tasks/, uses YAML frontmatter, and auto-refreshes the task dashboard. These are meaningful side effects beyond the schema, though it could also mention what the tool returns.

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 terse sentences: primary action, storage location, and key behavioral side effect. 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 22-parameter tool with no output schema, the description gives enough selection and invocation context: what it creates, where tasks live, what fields are supported, and the dashboard refresh side effect. It does not mention the returned task ID or how the agent should reference the created task, which is a minor gap given dependency-related parameters.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by grouping key parameters (priority, type, dependencies, scope isolation, context notes, acceptance criteria) and explaining that parameters become structured YAML frontmatter, which helps agents understand the data model 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?

Clearly states the verb ('Create') and resource ('new task in the vault's task queue') with the storage format ('structured YAML frontmatter'). It also distinguishes the tool from generic note creation by explaining that tasks are markdown notes in the Tasks/ folder.

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?

Usage is implied: 'Create a new task' signals this is for new tasks, and sibling tools like update_task and complete_task cover other lifecycle stages. However, the description never explicitly states when not to use this tool or names an alternative for related 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 are provided, so the description carries full responsibility for behavioral disclosure. It mentions the three actions but does not disclose that 'create' may overwrite an existing note, how 'append' behaves when the note does not exist, or what the tool returns. For a tool that can modify or overwrite content, this is a meaningful 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 compact, front-loaded with the core action, and wastes no words. The date-format note and storage-location note are both useful and directly relevant to correct invocation.

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 plus the fully documented schema provide enough for basic invocation, but the absence of an output schema and annotations means the tool lacks return-value and safety-context information. For a multi-action tool with create/overwrite and append behavior, the description is adequate but not 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 100%, so the schema already documents all four parameters and their meanings. The description adds a little value by emphasizing the accepted date formats and the configurable storage folder, but it does not go beyond the schema in any substantive way.

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

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

The description clearly identifies the tool's function with a specific verb and resource: get, create, or append to a daily note. The date support and 'daily note' concept help distinguish it from the sibling generic note tools like read_note, create_note, and update_note, though it does not explicitly name those alternatives.

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 context about supported date values and the configurable folder but gives no explicit guidance on when to use daily_note versus the generic note-reading or note-editing siblings. An agent would need to infer the intended use case from the tool name and description.

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 present, the description carries full responsibility for revealing behavior, and it does this well. It discloses that deletion is not permanent by default, that notes go to .trash/ following Obsidian convention, and that permanent=true causes a hard delete. This is exactly the kind of safety-relevant behavior an agent needs to know before invoking the 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 deliver the core operation, the default behavior, the exception, and the exact flag to trigger it. There is no filler, and the most critical safety information is front-loaded at the beginning.

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 only two simple parameters, no nested objects, no output schema, and no annotations. The description covers what the tool does, what the default consequence is, and how to switch to permanent deletion. This is sufficient for an agent to call 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 100%, so the schema already documents both path and permanent, including the default value and meaning. The description adds the term 'hard delete' and restates the trash behavior, which is mildly clarifying but does not provide significant additional meaning beyond the schema.

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

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

The description opens with a specific verb and resource: 'Delete a note from the vault.' It immediately distinguishes this tool from siblings like create_note, update_note, and read_note by saying what operation it performs, and it adds the key distinction between moving to .trash/ and permanent deletion.

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

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

The description clearly establishes the context for use: deleting a note. It also explains the default behavior and the condition for hard deletion with permanent=true. However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of full exclusion guidance.

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

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

With no annotations, the description carries the burden. It clearly communicates that this is a read-only aggregation via 'Get' and discloses the return content (active projects, blockers, decisions, etc.). It does not explicitly say 'does not modify state,' but the verb and return list make the behavioral profile sufficiently transparent.

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

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

Three short sentences with no filler: what it returns, what content is included, and when to call it. The timing guidance is front-loaded after the purpose, and 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 no output schema, the description still enumerates the returned briefing categories. All parameters are optional and fully explained in the schema. For an aggregation/overview tool, everything an agent needs to call it appropriately is present.

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

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

Schema description coverage is 100%, so the parameters (hours, project_id, include_completed) are fully documented in the schema. The description adds little parameter-specific meaning beyond 'recent activity,' matching the baseline for high 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?

States a specific verb and resource: 'Get a structured briefing of the vault's current state.' It enumerates the contents of the briefing, making it clearly distinct from narrower sibling tools like get_project_status or list_tasks.

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 when-to-use guidance: 'Call this FIRST in any new session to understand what's going on.' It does not mention when to avoid it or name alternatives, 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?

No annotations are provided, so the description carries the full behavioral burden. 'Get rollup status' clearly signals a non-mutating read operation, and the description discloses the aggregated output contents. It does not cover edge behaviors like invalid project IDs, but for a simple status lookup this is 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?

The description is two sentences with no filler. The core purpose and output contents are front-loaded, and the practical ID-lookup guidance is appended without 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 single-parameter read-only status tool with no output schema, the description is complete: it names the parameter source, documents the lookup path, and enumerates the expected return fields. Nothing an agent needs to correctly invoke and interpret this 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 input schema already provides 100% coverage for the single parameter, including an example format and the note to use list_tasks(type: 'project') to find project IDs. The description repeats the list_tasks guidance but adds no new semantic meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Get rollup status of a project', then enumerates exactly what that includes: progress percentage, status breakdown, active agents, overdue tasks, and blockers. This makes it clearly distinct from sibling tools like list_tasks, get_usage_report, and get_context.

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 actionable context: use this tool when you need rollup project status, and it explicitly tells the agent how to discover project IDs via list_tasks(type: 'project'). It does not name alternatives or exclusions, but the use case is clear enough for a single-purpose read 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 disclosure burden. It does disclose the return behavior ('Returns totals and breakdowns by agent and model') and implies a side-effect-free read operation. It omits details like data freshness, empty-result behavior, or permission requirements, but the core behavioral profile of a simple aggregation query is conveyed.

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 filler: the first front-loads the action and scope, the second states the return value. Every clause earns its place, and there is no repetition of schema content.

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

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

For a tool with 5 optional parameters, no annotations, and no output schema, the description covers the core invocation semantics: what it aggregates and what it returns. Gaps remain around the default time range when dates are omitted, whether breakdowns are always by both agent and model, and the response format — but these do not block a basic correct invocation.

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

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

Schema description coverage is 100%, so each of the 5 parameters is already documented in the schema, warranting the baseline 3. The description adds mild connective meaning by naming 'tasks, agents, projects, and time ranges' as aggregation dimensions, which maps to the task_id/agent_id/project_id/from_date/to_date filters, but it does not explain interdependencies or defaults.

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 ('Aggregate') with a clear resource ('token and cost usage'), then specifies the scope ('across tasks, agents, projects, and time ranges') and the return shape ('totals and breakdowns by agent and model'). This clearly positions it as the query/report counterpart to sibling log_usage, so an agent can distinguish them 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?

The reporting use case is implied through the aggregation language, and the contrast with sibling log_usage (which records usage) is inferable. However, the description never explicitly states when to use this tool versus alternatives, nor any conditions or exclusions.

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 disclosure burden. It does disclose key behaviors: commit stages all changes, sync combines pull+commit+push, init adds a .gitignore, and remote_name defaults to origin. However, it omits side effects and failure modes such as what happens when pull or sync encounters conflicts, whether operations mutate the vault irreversibly, and what authentication or repository-state prerequisites exist.

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

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

The description is a single dense, scannable sentence with no filler. Each listed action maps directly to an enum value in the schema, and the 'Git version control for your vault' purpose 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?

For a multi-action tool with no output schema and no annotations, the description covers all ten actions and their primary parameter semantics well enough to invoke the tool correctly in most cases. The main remaining gaps are return-value formats and conflict/error behavior, but the schema fills in parameter details and the action list is comprehensive.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine value by explaining action-specific parameter usage: path is for diff, limit for log, message for commit/sync, and remote_name/remote_url for remote_add. It also clarifies the combined behavior of 'sync' beyond what the schema alone states.

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

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

The description opens with 'Git version control for your vault' and enumerates ten distinct actions with one-line explanations. This makes it unmistakably a multi-action git tool and separates it from the note/task management 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?

No sibling tool duplicates git functionality, so alternative routing is unnecessary. Instead, the description provides concrete per-action guidance: 'sync' means pull+commit+push, 'diff' takes a path, 'log' takes a limit, and 'commit' auto-generates a message. It lacks explicit 'when not to use' exclusions, but intended usage 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 provided, the description carries the full burden of behavioral disclosure. It does add useful behavior beyond the name, namely that each result shows current workload and capacity and that filtering by availability is possible. However, it does not explicitly state that this is a read-only operation, whether any registration or permission is required, or whether results are limited or paginated.

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, dense sentences with the primary action front-loaded. Every clause adds information: what is listed, how to narrow the list, and what the output includes. There is no filler or repetition of schema content.

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

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

For a simple optional-parameter list tool, this description is largely complete: it names the resource, the filter options, and the primary output fields. Since there is no output schema, mentioning workload and capacity is valuable. A small gap is the lack of any note about default behavior or result shape beyond those two fields, but this is minor given the simplicity of the 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 100%, so the schema already documents all four parameters in detail. The description lists filter dimensions like capability, tag, status, and availability, which maps onto the schema, but it adds no additional semantic meaning beyond what the parameter descriptions already provide. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource, 'List registered agents', and immediately adds distinguishing details: the supported filters and the workload/capacity information shown. This clearly separates it from nearby sibling tools like list_tasks or list_vault, and there is no ambiguity about what object it operates on.

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 explains what filters can be applied but gives no guidance on when to choose this tool over related siblings such as suggest_assignee, get_usage_report, or register_agent. There is no mention of use cases, exclusions, or alternatives, so an agent must infer the appropriate context entirely from the tool's name and 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?

No annotations are provided, so the description carries the disclosure burden. It signals read-only behavior by saying 'Query' and 'Returns a filtered, sorted list.' However, it omits notable default behaviors such as completed tasks being excluded by default, what the sort order is, and whether tags/assignee filters are exact or 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?

Two efficient sentences front-load the action and result, then provide use cases. There is no filler; every phrase contributes to selection or invocation.

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 10 parameters fully documented in the schema and no output schema, the description supplies the key missing context: the task queue source, read-only intent, and usage scenarios. The main omission is out-of-scope behavioral detail like default active-only filtering and sort ordering, which would strengthen completeness.

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

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

Schema description coverage is 100%, with every parameter having a description, enum, or default, so the baseline is 3. The description adds only high-level filter categories already reflected in the schema and does not repeat detailed parameter semantics.

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

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

The description states a specific verb ('Query') and resource ('tasks from the vault's task queue'), and names the filtering dimensions: status, priority, type, or assignee. This clearly distinguishes it from mutation siblings like create_task, update_task, and complete_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 concrete usage contexts: 'find available work or monitor progress.' It does not explicitly name alternatives or state when not to use the tool, but the read-only query intent is clear enough to guide selection among the sibling tools.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It usefully reveals that hidden folders (.obsidian, .trash, .git) are excluded by default and that recursion/depth is supported. However, it does not disclose the return format, ordering, path formatting, or whether hidden folders can be included despite the phrase 'by default'.

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 then add the most decision-relevant behavior: recursion depth control and hidden-folder exclusion. No wasted words or redundant restatements of parameter names.

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 listing tool, the description plus a fully documented schema cover the main usage decisions: what is listed, recursion behavior, depth limits, note-only filtering, and hidden exclusions. The absence of an output schema makes the missing return-format detail a minor gap, but the overall context is sufficient for correct invocation in most cases.

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

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

Schema description coverage is 100%, so all four parameters are already documented with names, defaults, and descriptions. The description reinforces the recursive/depth ideas but adds no new parameter-level meaning; a baseline of 3 is appropriate since the schema does the heavy lifting.

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: 'List files and folders in the vault.' It further clarifies scope with recursive listing support and hidden-folder exclusions, making it clearly distinct from siblings like read_note (which reads content) and search_vault (which searches).

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

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

The description implies when to use the tool—whenever the vault's file/folder structure is needed, especially with recursion or depth control—but it does not explicitly state when to prefer alternatives such as search_vault or read_note. There are no exclusions or direct comparisons with sibling tools.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It does reveal that decisions become persistent structured records and that future agents can find them via get_context, which is valuable. But it does not mention return values, whether entries are append-only, overwrite semantics, or any side effects beyond logging. The core behavior is clear, yet incomplete.

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 with no redundant phrasing. It front-loads the core action and resource, then adds the key value proposition. Every sentence contributes useful 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 schema is rich and fully documents all 11 parameters, so the description does not need to repeat field details. It supplies the missing context: why the log exists, what it captures at a high level, and how future agents should retrieve it via get_context. It is sufficient for a single-purpose logging tool, though it does not specify the return value.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only general thematic alignment—context, rationale, alternatives, consequences—which loosely maps to parameters but adds no new semantic meaning beyond what the schema already documents. It does not clarify formats, defaults, or relationships between fields.

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

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

The description clearly states a specific verb and resource: 'Log an architectural or design decision as a structured record.' It conveys the substance of the record—context, rationale, alternatives, consequences—which distinguishes it from generic note-taking. It does not explicitly name or contrast with sibling tools like log_discovery, but the focus on WHY things were done gives meaningful 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?

The description implies when to use the tool: when making an architectural or design decision that should be preserved for future context. It also hints at the consumption path via get_context. However, it does not provide explicit guidance about when NOT to use it or how it compares to alternatives such as log_discovery, create_note, or create_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 burden of explaining behavior. It states that the tool logs a structured note and implies persistence for future agents, but it does not clarify side effects such as whether an existing note is updated, duplicated, or how the note becomes searchable. This is useful but incomplete for a write 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 three tight sentences with no filler. It front-loads the core purpose, then adds the captured value and the motivating benefit, making it easy for an agent to parse quickly.

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

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

For an 11-parameter write tool with no annotations and no output schema, the description supplies the essential purpose and value proposition, but it omits expected return behavior, storage semantics, and how logged discoveries can later be found. The schema covers the input fields, but not these operational 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?

The input schema has 100% description coverage, so the description does not need to explain parameters. It does echo 'impact' and 'recommendations', which map to schema fields, but it adds no meaning beyond the schema's own detailed parameter descriptions.

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

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

The description names a specific action and resource: logging discoveries, gotchas, or TILs as structured notes. It clearly distinguishes this from generic note creation by emphasizing that it captures impact and recommendations and prevents future agents from re-discovering the same things.

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 for when to use the tool: whenever an agent or human learns something worth persisting for future work. It does not explicitly name alternatives like create_note or log_decision or state when not to use it, so it falls just short of full 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 disclosing behavior. It explicitly states that records are stored ('Stores structured usage records in the Usage/ folder') and that the tool may append to the Agent Log. This is meaningful transparency about persistence and side effects, though it does not cover permissions, overwrite behavior, or error cases.

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

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

Two sentences with no filler. The main action is front-loaded ('Record token/cost usage'), followed by the storage location and optional side effect. Every clause carries useful information.

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

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

For a straightforward logging tool with 100% schema coverage, the description conveys the essential behavior: what is recorded, where it is stored, and the optional side effect. It lacks any mention of return value or failure modes, but no output schema exists and the operation is simple enough that an agent can reasonably infer behavior. Slightly more detail on prerequisites would push it to a 5.

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

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

Schema description coverage is 100%, so all nine parameters already have descriptions in the input schema. The tool description mentions 'token/cost usage' and 'task or agent', which loosely maps to input_tokens/output_tokens/cost_usd and task_id/agent_id, but it adds no detail beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Record token/cost usage for a task or agent.' It clearly distinguishes this logging tool from siblings like get_usage_report (reading usage) and log_decision (recording decisions) by naming the exact data captured and the storage target ('Usage/ folder').

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

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

The description clearly states the context of use: whenever token/cost usage needs to be recorded for a task or agent. It also mentions an optional side effect ('appends usage summary to the task's Agent Log'), which helps an agent decide whether this tool is appropriate. However, it does not explicitly name alternatives or exclusion conditions, so it misses the top score.

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 disclosure burden. It usefully discloses YAML frontmatter as the source of truth, inline tag reading, and automatic deduplication. However, it leaves ambiguous whether add/remove affects inline tags as well as frontmatter, and does not describe side effects or failure behavior for a tool that mutates notes.

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, each carrying distinct information: operation scope, storage mechanism, inline-tag behavior, and deduplication. It is front-loaded with the purpose and contains 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 simple 3-parameter tool the schema covers parameters well, but with no annotations and no output schema the description omits what a caller should expect on 'list' (e.g., combined frontmatter+inline tags) and whether mutations rewrite only frontmatter. This is usable but not fully complete.

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

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

All three parameters are already fully described in the schema (100% coverage), so the description adds little parameter-level detail. The YAML/inline/deduplication context enriches meaning but is not needed to interpret individual 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 opens with a specific verb set — read, add, remove — and a clear resource (tags on a note). It further pinpoints the tag storage location (YAML frontmatter) and that inline #tags are also read, which separates it from generic note read/update 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 intended use is implied by the action list, but there are no explicit statements about when to choose manage_tags over read_note/update_note, nor any exclusions such as 'for full note edits use update_note'. An agent can infer the niche but is not guided toward the right alternative.

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 disclosure burden. It discloses that the operation is a read and lists returned data categories (parsed frontmatter, markdown content, tags, file stats), which communicates non-destructive behavior and output scope. It does not mention error conditions, permissions, or how missing paths are handled, but for a simple read operation this is a reasonable minimum.

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

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

The description is short and front-loaded with the action, using two sentences. There is slight redundancy between 'content, frontmatter, tags, and metadata' and 'parsed frontmatter, markdown content, tags... and file stats,' but it remains compact and free of 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 two-parameter read tool with no output schema, the description adequately covers what the agent should expect: parsed frontmatter, markdown content, tags, and file stats. It could add note-level failure behavior or clarification about path resolution, but those are either in the schema or minor for the tool's simplicity.

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

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

Schema coverage is 100%, and the schema already documents both 'path' and 'includeRaw' with meaningful descriptions. The description adds no parameter-specific guidance beyond the schema; it does reinforce that the output contains parsed content and optional raw content, but this is not substantial added semantic 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 begins with a specific verb and resource: 'Read a note's content... from the vault.' It clearly distinguishes itself from siblings like search_vault, create_note, update_note, and delete_note by stating it retrieves an existing note's details. It also specifies what is returned, making the tool's purpose unmistakable.

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

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

The description clearly implies this tool is for reading a specific note's content and metadata by path, which gives an agent clear context for when to invoke it. It does not explicitly mention alternatives or exclusions, such as 'use search_vault to find notes first,' so it stops short of full guidance, but the read vs. search vs. write distinction is inferable.

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 available, the description carries the full burden of behavioral disclosure. It explicitly states the key side effect: 'Creates or updates an agent profile in the Agents/ folder.' However, it does not clarify whether updates merge or replace existing fields, what permissions are needed, or what the tool returns after invocation.

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, purposeful sentences: the first states the core action, the second adds the upsert and storage location, and the third gives the intended use. No filler or 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 gives enough context for a typical registration call: what the tool does, where it stores profiles, and why it exists. It could be more complete by describing overwrite semantics or return values, but the schema covers parameters well and the stated purpose is sufficient for most invocation scenarios.

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

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

The input schema already documents all 6 parameters with high coverage, so the baseline is 3. The description adds minimal semantic value beyond echoing the concepts of capabilities, tags, and capacity. It correctly groups the most relevant parameters but does not explain them in more depth than 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 uses a specific verb ('Register') with a clear resource ('agent profile') and names the relevant fields (capabilities, tags, capacity). It further clarifies the operation as an upsert ('Creates or updates') and distinguishes itself from siblings like list_agents or suggest_assignee by focusing on agent registration.

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 'Used for capability-based task routing' gives a clear functional context for when this tool is appropriate. It does not explicitly mention alternatives or when not to use it, but the context is strong enough for an agent to infer the primary use case.

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

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

With no annotations, the description carries the full behavioral disclosure burden. It does disclose meaningful state transitions: approve sends to completed and unblocks dependents, reject sends to revision_requested. However, it omits the behavior of the schema's 'request_changes' action, feedback requirements, and any idempotency or reversibility notes.

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 concise sentences with no filler. The key action and status precondition are front-loaded, and every sentence contributes either scope, usage context, or state-transition behavior.

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 no annotations and no output schema, the description covers the main invocation context and critical state outcomes. It is not fully complete: the 'request_changes' action is omitted, feedback requirements are not mentioned, and the response/return behavior is not described. Overall, it is adequate but has clear 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 100%, so the baseline is 3. The description adds value beyond the schema by explaining that approve unblocks dependents and reject moves the task to revision_requested, enriching the action enum semantics. Feedback and reviewer parameters remain schema-only, but this is acceptable given full 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 and resource: 'Approve or reject a task in needs_review status.' It also adds the human-gating context, which distinguishes this tool from sibling automation-oriented tools like complete_task. The core purpose is unambiguous, even though the schema's third action 'request_changes' is not named in the description.

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

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

The description clearly states the precondition ('task in needs_review status') and the intended usage context ('Used by humans to gate high-risk work'). It does not explicitly name alternatives or state when not to use this tool, so it stops short of full 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 burden of behavioral disclosure. It discloses the return format (matching files with line numbers and context), regex support, and folder filtering. It does not mention limitations like default result caps, case sensitivity behavior, or whether the search is read-only, though these are partially present in 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 three short sentences with no filler. The primary purpose is front-loaded, followed by useful capabilities and return format. Every sentence contributes 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 search tool with five parameters and no output schema, the description covers the essential behavior and return information. It does not explain result limits or case sensitivity, but those are documented in the schema. The description is sufficient for an agent to know what to expect from the tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds brief context for the folder and regex parameters, but it does not meaningfully expand on query semantics or the maxResults/caseSensitive parameters beyond what the schema already states.

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

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

The description clearly states a specific action (full-text search), a resource (all notes in the vault), and key capabilities (plain text, regex, filtering by folder). It distinguishes itself from sibling read/list tools by emphasizing search-plus-context, though it does not explicitly name an alternative.

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

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

The description implies when to use the tool: when you need to find matching notes by content, especially with regex or folder scoping. However, it gives no explicit guidance about when not to use it or how it compares to list_vault, read_note, or other discovery 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 are provided, so the description must carry the disclosure burden. It clearly indicates the tool analyzes a task and returns suggestions, which implies a non-mutating behavior. However, it does not state whether this is read-only, whether agents need to be pre-registered, or how availability and success rate are determined.

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, information-dense sentence that front-loads the core behavior and criteria, then states the output. Every clause earns its place 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?

For a low-complexity single-parameter tool with no output schema, the description is reasonably complete: it states the input, the ranking criteria, and that output is ranked suggestions. It could add more detail about the suggestion result shape or failure conditions, but these are minor 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 100% and the task_id parameter is already documented with a type and an example. The tool description adds no new parameter-level meaning, so it stays at the baseline 3 without compounding 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?

States a specific verb ('suggest'), a clear resource (agents for a task ID), and explicit selection criteria ('capability match, tag overlap, availability, and success rate'). It also names the return value ('ranked suggestions'), and this clearly differentiates it from siblings like list_agents.

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 'Given a task ID' and the verb 'assign' imply the intended use case: when an agent needs to decide who should handle a task. However, there is no explicit guidance about when to prefer this over list_agents, claim_task, or update_task, and no exclusions or alternative recommendations.

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 explain the three modes and that frontmatter fields are merged, but it does not address edge behavior such as handling missing notes, whether replace mode preserves frontmatter when the frontmatter parameter is omitted, or what the return value indicates.

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 with the core action and modes front-loaded, followed by the frontmatter behavior. Every sentence carries meaningful information 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?

The combination of the description and the detailed schema gives an agent the essentials: required path, mode semantics, content behavior, and frontmatter merging. The lack of an output schema and annotations leaves some gaps around return values and error cases, but the tool is simple enough that the core calling contract is substantially 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 100%, and the schema already documents mode behavior, path, content, and frontmatter merge semantics in detail. The description mostly restates what the schema provides, so it adds little parameter-level value beyond the structured definitions.

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 ('Update'), a resource ('an existing note'), and explicitly enumerates the supported modes and frontmatter merging behavior. This clearly distinguishes it from siblings like create_note, read_note, and delete_note.

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 'an existing note' implies this tool is for modifying notes that already exist, giving some usage context. However, it does not explicitly state when to prefer update_note over create_note for missing notes, or over manage_tags/search_vault for related operations, leaving alternatives to inference.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses important behavior: updates target specific fields, appends Agent Log entries, and validates status transitions. It does not mention error responses, reversibility, or permissions, but the disclosed validation behavior is meaningful beyond a generic update description.

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, front-loaded with the core action, and uses only three sentences. Each sentence adds value: what can be updated, what side effects occur, and when to use the tool.

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

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

For a mutation tool with no annotations and no output schema, the description covers the main fields, the Agent Log side effect, and important validation constraints. It does not mention the scope or depends_on parameters, though those are fully covered in the input schema. The omission of explicit return/error behavior is a minor gap given schema richness.

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

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

Schema coverage is 100%, so the schema already documents all eight parameters. The description mentions several fields but adds little semantic detail beyond what the parameter descriptions already provide; the log append behavior is already reflected in the log_entry parameter description.

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

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

The description states a specific action—'Update a task's status, priority, type, or assignee'—and identifies the resource. It also mentions log appending and workflow progression, but it does not explicitly name sibling tools like claim_task or complete_task, so the differentiation is clear but not fully explicit.

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

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

The description gives clear context: 'Use this to move tasks through the workflow' and includes an example of valid vs invalid status transitions. It implies the need to claim tasks before completing them, but it does not explicitly state when to prefer claim_task or complete_task over 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 behavioral disclosure burden. It does a good job by specifying the four operational modes and the exact supported wikilink syntax variants (alias, heading, blockid). It does not explicitly state that operations are read-only or describe return shape, but the navigation framing and action definitions strongly imply no side effects.

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

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

The description is compact and front-loaded: it opens with the resource, then enumerates all actions, and closes with syntax support. Every sentence adds useful information 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?

For a multi-action navigation tool with no output schema, the description covers all actions, the parameter roles, and the supported link syntax comprehensively. It stops short of describing return formats or error behavior, but these are minor given how clearly the actions define what will be found or listed.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context beyond the schema by documenting the supported wikilink syntax forms. It also reinforces the dual meaning of 'path' across resolve versus backlinks/outlinks, though the schema already captures most parameter semantics.

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

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

The description clearly names the resource (Obsidian [[wikilinks]]) and enumerates four concrete actions with definitions: resolve, backlinks, outlinks, unresolved. This makes the tool's purpose unambiguous and distinguishes it from sibling tools like search_vault and read_note.

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?

Each action is described with its intended use case, so an agent can pick among the actions. However, the description does not explicitly state when to prefer this tool over sibling tools like search_vault or read_note, and it offers no exclusions or prerequisites. 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.