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

With no annotations, the description carries the full burden and does well: it discloses the state change (clearing a stale warning), the ordering prerequisite (hash must be reported first, and by another tool), and the negative branch. It stops short of saying what happens if the hash is stale or not reported, or whether the clearing is idempotent/reversible.

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, front-loaded with the action, then the precondition, then the alternative branch. No filler; every clause carries decision-relevant 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 two-parameter state-changing tool with no annotations and no output schema, the description covers effect, precondition, and alternative path adequately. Minor gaps (failure modes when the hash is unreported or stale, and what is returned after acceptance) remain, but 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?

Schema coverage is 50% (only 'model' is described). The description compensates by clarifying the target: ref_id refers to a linked file whose hash must be reported through report_file_hashes rather than passed here, which prevents an agent from guessing at a hash parameter. It adds real meaning beyond the schema, though it never states ref_id's format.

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

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

States a specific verb+resource effect: clearing the stale warning on a linked file. It also scopes the action with the precondition ('once you have read the change') so an agent knows exactly what state transition this performs, distinct from siblings like get_file_context or update_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?

Explicit when-to-use ('note still holds') and when-not ('if the note no longer holds, fix the note instead'), routing the agent to the alternative path. It also names the required prior step (report its current hash first, via report_file_hashes), so the sequencing is unambiguous.

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

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

Annotations already establish readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds the behavioral frame the annotations cannot: the report is derived 'from the log' and is a composite of enumerated categories, which effectively serves as a proxy for the return shape given there is no output 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?

Two dense sentences plus one short directive, front-loaded with the outcome and scope before the format guidance. Every clause carries information — the enumeration, the format rationale, and the period preference — with 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?

With no output schema, the description compensates by enumerating the report's sections, and with annotations covering safety and 100% schema coverage covering parameters, little is left unexplained. An agent has enough to call it and to anticipate what comes back.

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 baseline is 3, but the description genuinely adds meaning beyond the schema: it explains why to pick 'markdown' vs 'json' and notes a preference for named periods over 'all'. It does not, however, clarify the from/to override relationship with period or the project scoping.

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 the resource ('activity report' over a window) and enumerates exactly what it aggregates — tasks completed/opened, time in 'doing', lead time, models, decisions, dead ends, open questions. That content list distinguishes it from siblings like list_tasks or search, which return raw items rather than an aggregated log summary, though it never names a sibling explicitly.

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

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

It gives real selection guidance: format 'markdown' 'to hand on' vs 'json' 'to reason over', plus 'Prefer a named period to all'. These are clear conditions for choosing among options, but there is no when-to-use-this-instead-of-alternatives statement (e.g., vs list_tasks/search) and no 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?

With no annotations, the description carries the full behavioral burden and falls well short: it never states this is a write/mutation, whether records are deduplicated, what confirmation is returned, or any permission requirements. The account-wide hint it does offer is already stated in the schema's `project` description, so it adds no new 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?

Two tight sentences, no filler: the first defines the qualifying knowledge domain and the second front-loads the account-wide scoping rule. Every clause earns its place.

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

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

A seven-parameter mutation tool with no annotations and no output schema gets only ~20 words. An agent cannot tell from the description whether adding is idempotent, what happens to referenced observations, or how insertion relates to update_context/delete_context — substantial gaps for a write 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 coverage is 57%, so the description must pay some of the freight; it does explain the omit-project/cwd scoping semantics, but that duplicates the `project` parameter's own schema description. The other four parameters (body, title, model, from_observation_id) get no clarification, so the description neither compensates for the coverage gap nor adds much 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 names the resource precisely — durable knowledge of four kinds (decision, convention, gotcha, preference) that map to the `kind` enum, so an agent knows what qualifies for insertion. However, it never states a verb explicitly and does not distinguish itself from siblings like update_context or get_context, so selection still relies on the tool name.

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

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

The only guidance is a scoping shortcut ('omit `project` and `cwd` to make it account-wide'), which is invocation detail rather than when-to-use guidance. Nothing tells the agent when to record knowledge at all, or whether this is preferred over update_context, which is a real ambiguity given the sibling list.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses that sibling tools implicitly register projects from cwd, which is real behavioral context. However, it says nothing about duplicate-name behavior, idempotency, or whether re-registering an existing project errors or upserts — the key unknown for a create/register mutation.

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

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

Two short sentences, zero filler, and the highest-value fact (that other tools usually make this unnecessary) is front-loaded right after the purpose. Nothing repeats the schema.

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

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

For a 6-parameter mutation with no annotations and no output schema, the schema is well documented but the description omits the one thing structured fields cannot supply: what happens when the name/slug already exists and whether this is safe to call repeatedly. Adequate but with a clear gap.

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

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

Schema description coverage is 100% and the descriptions are rich (repo_url as project identity across machines, summary guidance, slug defaulting from name), so the schema does the heavy lifting. The description only adds 'by name,' which confirms name as the key. Baseline 3 applies.

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

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

States a specific verb and resource ('Register a project by name') and explicitly distinguishes itself from get_context and create_task, which auto-register a project from cwd. An agent can tell what this does and why it might be redundant 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?

Names the two alternatives and gives a clear when-not condition ('Usually unnecessary'), which is unusually strong routing guidance. It stops short of stating the case where this tool IS the right choice (e.g. registering a repo not reachable from the current cwd), so it is not fully explicit.

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

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

With no annotations, the description carries the full disclosure burden for a write tool. It usefully reveals a side effect — resolving `cwd` can create a project — and a data-freshness behavior via file hashing. However it omits any permission/auth expectations, and it references `repo_root`/`repo_url`, which do not exist in this tool's schema, creating behavioral confusion rather than clarity.

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

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

Three tight sentences, front-loaded with the purpose and then the project-resolution rule; nothing is padded. The third sentence's reference to non-existent parameters spends space on unusable information, which keeps it from a 5.

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

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

For an 8-parameter mutation tool with no annotations and no output schema, the description covers the trickiest part (project resolution and the `cwd`/`project` interaction) but says nothing about status, priority, files, or model behavior — it relies on the schema for those. The dangling `repo_root`/`repo_url` requirement is an unresolved gap an agent may try to satisfy and fail.

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 75%, so most parameters (priority, files, model, status) are already documented in the schema; description only adds guidance for `cwd`, `project`, and `body`, restating what the schema largely says. Worse, it claims registering a new project 'needs repo_root or repo_url too', but neither parameter is in the schema, so this instruction cannot be acted on. Baseline 3 with a mild accuracy penalty already absorbed by the misdirection.

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 states a specific action and scope: capture work that will not finish this session. That framing distinguishes it from session-scoped siblings like log_entry, and the rest of the description covers project resolution. It never states plainly 'creates a task record', but the name/title plus the scoping sentence make the purpose unambiguous.

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

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

Gives a clear usage condition ('work that will not finish this session') and routing rules between `cwd` and `project` for how the project is chosen. It stops short of naming exclusions or alternatives (e.g., use log_entry for work completed now, update_task to modify an existing task), so the agent must infer the boundaries.

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 supplied, so the description carries the full behavioral burden, and it discloses nothing about the mutation itself: whether deletion is reversible, whether confirmation or elevated permissions are required, or what happens to notes already referenced elsewhere. It only conveys intent for use, not the consequences or mechanics of the destructive action.

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

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

Two telegraphic clauses with zero filler, and the delete criterion is front-loaded before the update_context redirection. The terseness costs a bit of grammatical completeness (no explicit verb for what happens), but 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?

For an unannotated destructive tool with no output schema, the description covers the routing decision well but omits any statement of effects, reversibility, or the post-delete state. An agent knows when to call it, but not what calling it costs.

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%: context_id is documented in the schema (and the schema description itself repeats the update-context preference), and the optional model param is self-explanatory. The description adds no syntax, format, or identifier-source detail beyond that, 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 tool name and title carry the verb+resource ('delete_context' / 'Remove a context note'), but the description itself never states that it removes the note identified by context_id. It instead describes only the selection criterion, so the actual operation must be inferred from the name. It does, however, implicitly distinguish itself from update_context, which helps disambiguation.

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 defines when to delete (a note that should never have been written: wrong project, or superseded to the point of misleading) and when not to, naming the alternative tool ('merely out of date: update_context'). The edge case boundary between delete and update is stated rather than 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 full behavioral burden; it does disclose a genuine semantic policy (destructive removal is reserved for factually-wrong entries, not superseded ones). However, it says nothing about reversibility, whether the delete is soft or hard, permission requirements, or behavior when entry_id doesn't exist. Useful intent signal, incomplete operational profile.

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

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

Three tight sentences, front-loaded with the selecting condition before the alternative. The final 'Not for tidying' is a slight restatement of the append redirect but functions as a real exclusion, so there is minimal waste.

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?

No output schema and no annotations, so the description must stand alone. It covers the decision policy well but omits the mechanics an agent needs for a destructive call — reversibility, effect on the surrounding log, and result/error behavior — leaving 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 50% and entry_id — the required parameter — has no description at all. The description discusses entry content ('wrong task, a decision never made') but gives no guidance on identifying or sourcing the entry_id, so it fails to compensate for the 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 title supplies the verb+resource ('Remove a log entry') and the description sharpens it with the decisive criterion for removal ('wrong when written'). It also contrasts against the append path for superseded entries, so an agent can distinguish it from log_entry without opening a schema. It never states 'deletes' in the description body itself, but the combined title/description is unambiguous.

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

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

Explicit when-to-use ('entry that was wrong when written'), when-not ('overtaken by later work is history, not wrong: append instead'), and an additional exclusion ('Not for tidying'). The agent is given both the trigger and the redirect to an alternative behavior.

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

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

With no annotations, the description carries the full burden and does cover the critical traits: irreversibility ("Not recoverable") and cascading deletion of all child resources. It omits permission/auth requirements, what happens on a confirm mismatch, and what the call 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 short sentences, zero filler, with the destructive consequence front-loaded ahead of the confirmation mechanics. Nothing repeats the title or 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 three-parameter destructive tool with complete schema coverage and no output schema, the essentials are present: scope, irreversibility, and the human-approval gate. Permission requirements and the failure mode for a wrong `confirm` value are the remaining 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's note that `confirm` must be the project's slug duplicates the schema's own wording for that field rather than adding new syntax or format 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?

States a specific verb and resource plus the blast radius ("Removes a project and everything under it"), which lets an agent distinguish it from the sibling delete_context. It never names an alternative sibling, so the differentiation is inferential rather than 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?

Gives a clear precondition for invocation — "Ask the human first" — which is exactly the guidance an agent needs before triggering an irreversible tool. It stops short of naming when not to use it or which sibling handles narrower deletion.

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 only declare readOnlyHint and idempotentHint; the description goes well beyond that with cap limits (fifty tasks, three entries per kind), byte budgets, the guarantee that nothing is truncated and every record keeps `id`/`head`, and the meaning of a null `body`. It also disambiguates the two families of omission counters and explains idle-task handling after 14 days.

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 purpose and the 'call it first' instruction are front-loaded before the truncation mechanics, and nearly every clause carries distinct operational information. The cost is a single dense block of backticked jargon that is hard to scan, and a few details (the `focus` semantics) are repeated from the schema.

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

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

There is no output schema, so the description must carry the return contract itself, and it does: record shape (id/head/body), both counter families, the idle_tasks shape, ranked_by fields, and the summary_missing signal with the remedy. An agent can interpret every branch of the response without further sources.

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, but the description adds real semantic weight: `focus` spends budget on relevance rather than recency and 'can only move a record up, never drop one', plus the interaction between `focus` and the ranked_by fields. It adds less on `model` and `create_if_missing`, which the schema already carries.

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, concrete framing ('The session-start briefing') and enumerates exactly what it returns: standing rules, decisions, dead ends, open questions, open tasks with linked files, and the last handoff. It also distinguishes itself from siblings by naming get_task and get_context_note as the tools that read the bodies this one truncates.

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 it first, with `cwd`' is an explicit ordering instruction, and the description routes follow-up reads to get_task/get_context_note and the summary gap to update_project. It also explains when `focus` is worth supplying versus letting recency drive the budget.

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 and idempotentHint, so the safety profile is covered. The description adds genuine behavior beyond that: a null body signals truncation and is 'never empty', which is the signal an agent needs to distinguish an unreached note from a legitimately blank one, plus the routing rule that entries belong to get_task.

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 dense sentences with no filler, and the core statement of what is returned leads. The elliptical phrasing ('a note the briefing's budget did not reach') costs a little parse time, but every clause carries information.

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

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

With no output schema, the description correctly states what comes back (the whole body) and what a null body means, which is the main return-value question for this tool. Missing only edge behavior such as unknown/unauthorized context_id, which is minor for a read-only lookup.

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 both `model` and `context_id` are already documented in the schema, including where context_id comes from. The description only echoes the search-hit provenance and adds no syntax, format, or constraint detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific resource and scope: 'The whole body of one context note', contrasted with the truncated bodies returned by get_context's briefing and the snippets returned by search. It implicitly separates itself from those siblings via the 'budget did not reach' and 'search snippet' framing, though it never names get_context or search directly, so an agent must infer the contrast.

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?

Two concrete triggers are given: a note whose body is null because the briefing's budget truncated it, and a search snippet you need the rest of. It also routes the adjacent case correctly with 'Entries are read with get_task', telling the agent which sibling handles entry-type content. No explicit exclusions or prerequisites, but the when-to-use is unambiguous.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds real value on top: exactly what comes back (tasks with their dead ends and decisions, notes in full) and the path-resolution behavior. The note that absolute and relative paths fold to the same answer, so a note linked on one machine is found from another, is behavioral context an agent cannot infer from 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?

Four sentences, front-loaded with the payload description and followed by the when-to-use cue and the path/repo semantics. The aphorism about dead ends costing an afternoon is longer than strictly needed, but it carries the argument for calling the tool rather than being 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?

With no output schema, the description carries the return-value burden and discharges it by enumerating what is returned (tasks, dead ends, decisions, full notes). Combined with the path/cwd/project resolution rules and the calling trigger, an agent has everything needed to invoke this read-only 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 coverage is 100%, so the baseline is 3; the description goes beyond the schema by explaining that `cwd` or `project` says which repository is being asked about, which is the non-obvious disambiguation when a path could resolve in several repos. It does not explain the `model` parameter at all.

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

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

The description names a specific resource and scope: everything todox has recorded against one file — tasks that touched it plus their dead ends and decisions, and the context notes attached to it in full. That aggregation is distinguishable from a single-note fetch, though no sibling (get_context, get_context_note, search) is named to sharpen the contrast.

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?

"Ask before editing a file you have not seen this session" gives a concrete triggering condition, and the cost/benefit framing (a dead end costs nothing to read and an afternoon to rediscover) reinforces why. It does not, however, state when NOT to use it or route to an alternative such as search or get_context_note.

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 and idempotentHint, so safety is covered. The description adds real behavioral detail beyond that: the log is truncated to the newest 200 entries with an `entries_omitted` signal, and linked files carry fresh/changed/missing classification. It still omits failure behavior for an unknown task_id.

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 tight sentence with no filler, and the truncation caveat is correctly placed inline rather than buried. It is telegraphic (a noun phrase with no verb), which is efficient but slightly less immediately parseable than a full statement of action.

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

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

With no output schema, the description carries the burden of describing the return, and it does cover the log window and file-freshness flags well. However, it says nothing about the task's own fields, behavior on a nonexistent ID, or whether linked files are always present — gaps an agent would need to guess at.

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 only 50%: `model` is documented in the schema while `task_id` — the sole required parameter — has no description anywhere. The description never mentions either parameter, so it does not compensate for the gap; at best 'One task' hints that task_id selects the record.

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 gives a specific retrieved resource (a single task) plus the two things bundled with it — its log and its linked-file statuses. 'One task' implicitly contrasts with the sibling list_tasks, but it never names that sibling or states the lookup key explicitly, so it falls short of a 5.

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 only implied: an agent can infer 'use this when you need one task in full detail rather than a list.' There is no explicit when-to-use, no when-not-to-use, and no named alternative such as list_tasks or get_context for narrower needs.

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

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

With no annotations, the description carries the full burden. It does disclose downstream behavior well (todox warns when a linked file changes; get_file_context can resolve path back to task/note), which is genuinely useful context. However it says nothing about whether re-linking a path duplicates or replaces an existing link, what happens on an unknown task_id, or idempotency — real gaps for a mutation tool with zero annotation coverage.

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 verb, resource, and exclusive target selection are front-loaded in the first clause, and the total length is reasonable. The em-dash-heavy single sentence with asides ('wherever that lives', 'a claude.ai artifact, say') is slightly run-on and slows parsing, but no clause is pure filler.

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

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

For a tool with no annotations, no output schema, and 50% parameter coverage, the description covers purpose and downstream effects but omits the return shape, failure modes, and re-link/duplicate semantics. An agent can call it, but cannot predict what happens to pre-existing links or how errors surface.

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 only 50% (task_id and paths are undocumented in the schema), so the description must compensate. It does explain the task_id/context_id either-or relationship and the acceptable forms of 'path', but the per-item 'note' sub-field and the 'model' parameter are never explained in either place, leaving half the surface opaque.

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

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

The description states a specific verb and resource ('Attach file paths to a task (task_id) or a note (context_id)') and immediately delimits the two mutually exclusive targets. It also names the inverse sibling (get_file_context), so an agent can distinguish this tool from lookups in the same family without opening any 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 'one or the other' constraint on task_id vs context_id is an explicit usage rule, and it clarifies that out-of-repo paths and URLs are in scope. It never states when to use this instead of a sibling such as unlink_file or when linking is inappropriate (e.g., non-existent paths), so it stops short of true 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?

Annotations only cover the safety profile (readOnlyHint, idempotentHint), so the description must add the rest — and it does: activity-based ordering, inclusion of counts and paths, and the non-obvious behavior that empty projects are omitted yet still resolvable by slug or path. That last point is genuine behavioral value an agent would not otherwise know; it stops short of describing pagination or result size limits.

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

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

Two compact sentences with the result shape front-loaded and the exception case second. No filler, no restatement of the tool name or title, and the parenthetical flag name is the only mildly cryptic element.

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

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

With no output schema, the description is the only place return values can be explained, and it does sketch them (ordering, counts, paths). What 'counts' counts (tasks, notes, or both) is left ambiguous, which is a minor but real gap for a listing 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?

There is a single optional parameter (model) with 100% schema description coverage, so the schema already fully documents it. The description adds no further meaning about that parameter, which is the expected baseline when 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?

Names the resource (projects) and specifies the exact result set: projects holding a task or a note, sorted newest-activity-first, carrying counts and paths. It also states a scope constraint (empty projects omitted), which distinguishes it from a naive 'all projects' listing. It does not, however, explicitly differentiate itself from list_tasks or other enumeration 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?

There is no when-to-use or when-not-to-use statement, and no alternative is named. The note that empty projects are excluded tells the agent about coverage, but it does not tell the agent when this tool is the right choice versus list_tasks, get_context, or search.

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 idempotentHint=true, so the safety profile is covered. The description adds the status-filtering behavior and default scope, which is modest but real added context beyond the annotations. No pagination, ordering, or return-shape disclosure though.

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?

Extremely short, which is efficient, but it's a sentence fragment rather than a front-loaded structured sentence. It's under-specified rather than concise – the brevity comes at the cost of substance.

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 no output schema, the minimum viable bar is met because the annotations carry the safety profile. However key behaviors – default status, the project/cwd either-or requirement, ordering, pagination – are only in the schema, not surfaced or clarified by the description.

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 75% and the schema documents status (with default 'open'), cwd, and model itself. The description echoes the status filter but adds nothing about project/cwd mutual exclusivity (the anyOf constraint) or the model param, which is the most cryptic field.

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 verb (list) and resource (tasks) with a scoping note about projects and status filtering, so the purpose is discernible. But it's a fragment, not a sentence, and adds nothing to distinguish it from siblings like get_task beyond the implicit list-vs-single distinction.

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

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

No indication of when to use this versus get_task, or versus search. The status filtering mention hints at scope but provides no when/when-not guidance or named alternatives.

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

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

With no annotations, the description carries the full burden and does disclose real behavior: a question closes only via `answers_entry_id` ('nothing else closes one'), closed questions stay readable through get_task, and `from_observation_id` marks an observation handled so it leaves the briefing. It omits whether entries are editable/deletable after append and any auth or rate considerations.

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

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

Three tight sentences, front-loaded with the verb and the enum, then the headline/body constraint, then the closure rule. 'Keep the body to a screen' overlaps with the schema's own body guidance, a minor redundancy in an otherwise waste-free description.

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

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

For a 7-parameter mutation tool with no output schema and no annotations, the description covers the non-obvious behaviors an agent needs — entry kinds, body sizing, question closure, observation handling. The self-descriptive `model` and `author` parameters are left entirely to the schema, a small residual 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 a reasonably high 71%, and the schema already explains `kind`, `body`, `answers_entry_id`, and `from_observation_id` in detail. The description reinforces the closure semantics of `answers_entry_id` but adds little new meaning, and it says nothing about `model` or `author` — the baseline 3 for schema-driven parameters 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 — 'Append one entry' — and enumerates the five entry kinds, so the agent knows exactly what this tool produces. It does not explicitly contrast itself with lookalike siblings such as add_context or update_task, which is the only thing keeping it from a 5.

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

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

There is one genuine conditional: 'Settling an earlier question? Pass its id as `answers_entry_id`', which tells the agent when to reach for that parameter. Beyond that, there is no guidance on when to log an entry versus using add_context or update_task, so usage is mostly implied by the kind enum.

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

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

With no annotations, the description carries the full burden and does so: it discloses irreversibility ('Not undoable'), destruction ('`from` stops existing'), the preservation guarantee for both sides' data, and the human-confirmation requirement. It even names a required post-call follow-up (setting repo_url on the survivor).

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 dense sentences, front-loaded with the destructive action and its irreversibility before any follow-up advice. No filler clauses and nothing repeated from the schema verbatim.

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 destructive, annotation-free, no-output-schema tool the description covers the essentials: what dies, what survives, irreversibility, and confirmation workflow. It does not address conflict handling (e.g., colliding task names) or what the survivor looks like after the merge beyond repo_url, which leaves a small gap.

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

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

Schema description coverage is 100%, so all four parameters are already documented, and the description largely restates them (from = duplicate, confirm = slug of from). It adds the procedural requirement that confirm be typed after asking the human, but that is a workflow note rather than new parameter semantics; baseline 3 applies.

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

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

States a specific verb and resource (fold a duplicate project into the real one) plus the exact data that migrates: tasks, entries, notes and paths. It is immediately distinguishable from siblings like delete_project or update_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?

Gives an explicit triggering scenario ('same repository registered twice (`todox` and `todox-2`)') and a required pre-call step ('ask the human first'), which is clear usage context. It stops short of naming an alternative tool (e.g., delete_project) for the case where the duplicate's data should not be kept.

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 only declare readOnlyHint and idempotentHint; the description adds substantial behavior beyond that — relevance ranking, independent term matching, phrase quoting, English/Turkish stemming, substring fallback, snippet-per-hit, default limit of 30, and explicit exclusions (file paths and project names are not searched). It also discloses the non-obvious rule that a project filter still returns account-wide 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?

Front-loaded with purpose and ranking before tactical detail, and no sentence is filler — every clause is actionable query guidance. It is dense to the point of being run-on (backticks, parentheticals, and semicolons stacked in one paragraph), which slightly hurts scanability but not information 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?

With no output schema, the description carries return-shape duty and delivers: ranked hits, snippets from the matching part, and a capped result count. Combined with the query-syntax and filter rules, an agent has everything needed to call this correctly on the first try.

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 60%, and the description compensates well for the gaps: it explains the kinds filter with use-case framing ('dead_end = has this been tried?'), the project filter's edge case, the limit default, and query syntax (stemming, quoting, minimum 3-character identifiers). The `model` parameter gets no description text, though the schema itself carries a usable example.

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 set — 'Full-text search over tasks, log entries and notes across ALL your projects, ranked by relevance' — and explicitly states scope (all projects) and ranking behavior. An agent can immediately distinguish this from siblings like get_context, list_tasks, or get_context_note, which retrieve rather than search.

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?

Unusually explicit about when to use filters vs not: 'Filters narrow, never search' and 'Leave both out unless the question has a shape'. It also gives failure-recovery guidance ('if a sentence finds nothing, retry with only the distinctive identifiers') and a language rule ('ask in the language the log is written in'). No sibling routing is given, but the when/when-not conditions are exhaustively covered.

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 and idempotentHint, but the description adds real behavior beyond them: the exact time window that counts as 'this session', what 'stale' means concretely (7+ days, nothing logged, by anyone), and how to read an empty result ('nothing is owed'). It also flags the payload is deliberately small (ids, titles, dates, one boolean), which sets size expectations without an output 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?

Very tight, information-dense prose with the actionable instruction front-loaded and no filler sentences. The telegraphic fragments ('Ids, titles, dates and one boolean -- small on purpose') occasionally read as terse shorthand, but each clause carries load.

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

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

With no output schema, the description does the right thing by describing the return shape, the meaning of empty results, and what `hint` is for. Remaining gaps are minor: `hint`'s structure is only gestured at, and the fact that one of `project` or `cwd` must be supplied is left to 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 the baseline is 3. The description still adds meaning: it defines what the `hours` window counts ('the tasks you changed or wrote on in this project'), which is the operative semantics of the parameter, and clarifies the project scoping that `project`/`cwd` select. It does not explain the `model` parameter or the project-or-cwd requirement, so it stops short of full 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 defines two concrete output buckets (`yours`: tasks you changed on in this project within `hours`, with handoff status; `stale`: tasks stuck in 'doing' 7+ days) plus a `hint`, so the agent can infer this is a 'what do I still owe' status report. It never states a direct verb+resource sentence like 'returns outstanding work for this session', and it does not name a sibling such as activity_report or list_tasks, so differentiation is left to inference.

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 before finishing' gives an explicit trigger for invocation, which is unusually specific for a status tool. It supplies no when-not condition and names no alternative (activity_report, list_tasks) for agents that want a broader view, so the routing guidance is clear but one-sided.

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

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

With no annotations, the description carries the full burden and does disclose the highest-risk behavioral fact: the operation affects only the link, not disk contents, which is the functional equivalent of a non-destructive guarantee. It still omits idempotency/error behavior (what happens if ref_id is already unlinked) and any permission requirements, so it is helpful but not complete.

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

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

Two short sentences, zero filler, with the scope-of-effect reassurance front-loaded immediately after the action. 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?

For a simple two-parameter, no-output-schema tool, the description covers action, triggering condition, and effect scope, which is enough to call it correctly. The only real gap is not steering the agent toward or away from the adjacent link_files/delete_context tools.

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%: ref_id is documented as coming from the `files` of get_context or get_task, and model is described as the caller's model id. The description adds no parameter syntax, format, or constraint detail beyond repeating the link-not-file point, 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?

States a specific verb and resource (remove/unlink a file link) and clarifies the crucial distinction from file deletion: 'Removes the link, not the file' / 'Nothing on disk is touched.' It does not name a sibling (e.g. link_files for adding, delete_context for context deletion), so it stops short of a 5.

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 a concrete condition for use: links whose file 'was deleted, renamed or attached by mistake.' That tells the agent when this tool is the right one rather than a file deletion tool, though it offers no explicit when-not guidance or named 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?

With no annotations, the description carries the full burden and does disclose the key destructive trait: `body` replaces the whole note rather than patching it. However, it says nothing about what happens to unspecified fields (title/kind), permissions, or reversibility of an overwrite.

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

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

Two short sentences, front-loaded with the action and the overwrite warning; nothing is wasted or 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?

There is no output schema and no annotations, so the description must carry behavioral weight. It covers the central replacement semantic and the when-to-use case, but omits partial-update behavior for optional fields and any success/failure signal.

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 40%, with title, kind, and context_id undocumented. The description only restates the replacement semantics of `body`, which the schema already states verbatim ('Replaces the body outright'), so it adds little beyond structured data and does not compensate for the coverage 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?

States a specific verb and resource: rewriting a note that is wrong or out of date, with the body as the replacement payload. It implicitly separates itself from add_context ('correct rather than add a second note'), but never names the sibling, so an agent must infer the routing.

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 a clear trigger condition (note is wrong or out of date) and an exclusion (don't add a second, disagreeing note). It does not name add_context or delete_context as the alternatives, so the guidance is contextual rather than explicit.

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

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

With no annotations at all, the description carries the full behavioral burden and largely drops it. It never states whether this is a partial patch (omitted fields preserved) or a full replace, whether it requires ownership/permissions, whether changes are reversible, or what the response contains. The only behavioral-adjacent note — that summary should not be a changelog because 'those go stale' — is writing advice, not tool behavior.

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

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

Two sentences, front-loaded with the set of writable fields, with no filler. The second sentence is advisory rather than strictly necessary, which keeps it just short of maximally efficient.

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

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

For a six-parameter mutation tool with no annotations and no output schema, the description omits the two things an agent most needs: that `project` is the required target selector, and whether unspecified fields are left untouched. It also says nothing about the return value or error 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 coverage is 67%, and the description names four of the six parameters (name, root_path, repo_url, summary), adding a small amount of value by signalling which fields are writable. But it omits the required `project` identifier and `model` entirely, and the rich per-field guidance for summary and repo_url already lives in the schema, so net added meaning is modest.

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 verb 'Set' plus the enumerated fields (name, root_path, repo_url, summary) makes it clear this mutates an existing project's attributes, and the title confirms the resource. It does not explicitly distinguish itself from create_project or merge_projects, so an agent must infer that this targets an already-registered 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 second sentence gives a timing cue — use this right after registration to establish summary and repo_url — which is real usage context. However, there is no when-not guidance and no mention of the obvious alternative (create_project) or what happens if the project does not yet exist.

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

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

With no annotations, the description carries the full burden, and it does disclose a genuinely non-obvious side effect: setting status to 'doing'/'done' starts and stops a duration clock that feeds reports. However, it omits other important behavior such as permission/auth requirements, whether omitted fields are preserved or cleared, and what happens on an invalid task_id.

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

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

Two short sentences, front-loaded with the set of mutable fields, followed only by the non-obvious clock semantics. No filler, no restatement of the title or 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 6-parameter mutation tool with no annotations and no output schema, the definition is only partially complete: it never mentions the 'model' parameter, says nothing about partial-update semantics or error behavior, and does not explain which status transitions are legal from a given state.

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 only 17% (just 'model'), so the description must compensate; it names four updatable fields and explains the meaning of two status values. It leaves the 'model' parameter and the meaning of the 1-3 priority range unexplained, and gives no format detail for body/title beyond what the schema already states.

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

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

States a specific verb ('Change') plus the exact mutable fields (title, body, status, priority) of a task, so an agent immediately knows this mutates an existing task rather than creating one. It does not explicitly name sibling alternatives like create_task or get_task, so the differentiation is left to the tool name.

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 by the mutation verb and the fact that it edits an already-existing task, but there is no explicit 'use this when X, use create_task when Y' routing and no statement of preconditions or tasks that cannot be updated. The status-transition note is domain semantics rather than when-to-use guidance.

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