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

With no annotations present, the description carries the full burden of behavioral disclosure. It only states an action and target, but does not mention side effects (e.g., whether the item is appended or replaces), ordering constraints, permission requirements, or reversibility. For a mutating tool, this is a significant lack of transparency.

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, clear sentence with no superfluous words. It is concise and front-loaded, though it is under-specified in content. This dimension rewards efficient phrasing, so it earns a high score despite the lack of detail.

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

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

For a tool with six parameters, no output schema, and very sparse schema descriptions, the description is grossly inadequate. It does not explain what an agenda item is, the role of each parameter, or any implied constraints. An agent would not know how to correctly populate the fields, making the tool difficult to use 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 only 17% (only the estimate parameter has a brief description). The description itself provides zero explanation of parameters like type, week, project, or notes, nor does it clarify the meaning of the 'type' enum. Given this low coverage, the description should compensate, but it fails entirely to clarify any 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 (add) and the resource (weekly agenda board), making the tool's purpose unambiguous. It does not explicitly distinguish it from update_agenda_item or delete_agenda_item, but 'add' is a distinct operation and the target is specific. A minor gap is not naming alternatives when siblings exist.

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

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

No guidance is provided on when to use this tool versus the sibling tools such as update_agenda_item or get_agenda. There is no mention of prerequisites, sequencing, or scenarios where this tool is preferred. The description leaves usage entirely 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 must fully communicate behavioral traits, but it only states the obvious deletion operation. It does not disclose whether the deletion is permanent, if it is reversible, whether related entries are affected, or any other operational consequences beyond the verb 'remove'.

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, front-loaded sentence with no superfluous words or filler. It conveys the core purpose in six words and appropriately sized for a tool with one simple parameter.

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 operation with no annotations, no output schema, and an undocumented parameter, this description is too thin. It does not answer the essential questions of what the id refers to, how to interpret the result, or what happens after the item is removed; the agent is left with only the basic 'delete this resource' understanding.

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

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

The schema provides zero description coverage, so the description must compensate for the vague 'id' integer parameter. Although the sentence implies the id refers to an agenda item, it never explicitly explains that the id is the identifier of the item to be removed, nor does it clarify any validation or format requirements.

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 ('Remove') and the resource ('an item from the weekly agenda'), making it unambiguous what the tool does. It distinguishes itself from the sibling tools like add_agenda_item, update_agenda_item, and get_agenda through its verb and target.

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 offers no guidance on when this tool should be used versus alternatives, such as update_agenda_item for modifying an item or rollover_agenda for archiving the week. There are no explicit contexts, prerequisites, or exclusions, leaving the agent to infer the appropriate choice from the tool name alone.

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

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

No annotations are present, so the description carries the full burden of behavioral disclosure. It clarifies that the tool returns three categories of agenda items, which is useful context beyond what the schema provides. However, it does not explicitly state that the operation is read-only, does not mention authentication or rate limits, and gives no indication of what happens if the week field is malformed. For a simple getter this is acceptable, but it doesn't fully disclose behavioral traits.

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, well-structured sentence that front-loads the core purpose and immediately elaborates with the three key content areas. Every word contributes to understanding. There is no redundancy or filler, making it a model of concise, effective documentation.

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

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

Given the tool's low complexity (2 optional parameters, no output schema, no nested objects), the description is relatively complete. It explains what the agenda contains and thus what the caller should expect. The one gap is that it doesn't mention the 'week' parameter at all, though this is covered by the schema. For a simple getter, this level of completeness suffices.

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

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

The schema description covers the 'week' parameter thoroughly but leaves 'type' undocumented. The tool description compensates by listing 'focus items, coming up, and expected deliverables', which exactly correspond to the enum values of 'type'. This adds meaningful semantic meaning to the undocumented parameter and helps an agent populate the argument correctly. Only one parameter needed compensation, and the description delivered on that.

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 verb 'Get' and the resource 'weekly agenda', enumerating the three content categories (focus items, coming up, expected deliverables) that map directly to the schema's enum values. This gives a precise sense of what the tool returns. However, it does not explicitly differentiate itself from sibling tools like get_weekly_summary, so it doesn't fully eliminate ambiguity.

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

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

The description provides no guidance on when to use this tool versus its siblings. There is no mention of alternatives, no 'use this for X, use that for Y' routing, and no exclusions. An agent is left to infer that this is the general getter for weekly agenda data, but without explicit comparison to get_weekly_summary or others, the decision remains underspecified.

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 mentions that commits are 'recorded by the post-commit hook', which gives some transparency about how the data is collected, but it doesn't disclose behavior like what 'recent' means in time range (the default is 7 days but that's in schema), whether it sorts, or if it includes any other details. The description doesn't state any side effects (though likely read-only) or additional context. Given no annotations, more behavioral disclosure is expected.

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

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

The description is a single concise sentence, front-loaded with the action and resource. It mentions the recording mechanism, which adds useful context without redundancy. It's efficient and to the point.

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

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

For a single-parameter read tool, the description is fairly minimal. It doesn't explain what the response looks like (though no output schema exists), nor does it clarify the time window beyond the parameter. It doesn't mention any prerequisites or side effects. Given the simplicity, it's adequate but could include a bit more context on the 'recent' definition or that it returns commit details.

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 only parameter is 'days' with a default and min/max in the schema. The description does not explicitly explain 'days' beyond the implied 'recent', but since the parameter has a clear name and the schema provides constraints, the description doesn't need to add much. However, schema description coverage is 0%, so the description should compensate by explaining what 'days' represents, but it doesn't explicitly. Given there is only one parameter and it's self-explanatory, the description adds little value beyond the schema. Baseline 3 is appropriate because the schema is not documented but the parameter name is clear.

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

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

The description states the verb 'Get', the resource 'git commits', and the temporal scope 'recent', which is a clear purpose. It also hints at a recording mechanism ('recorded by the post-commit hook'), which adds specificity. However, it doesn't explicitly distinguish from any sibling tool, but none of the siblings are similar (get_work_log, get_weekly_summary are different resources). So slight deduction for no explicit differentiation, but the purpose is clear.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any context, such as 'use this for commit history', nor any exclusions. Since there is no explicit alternative, the tool could have stated that it specifically returns commits recorded by a hook, implying it's used when such data is needed, but that's only implied. No when-not or alternative guidance is provided.

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 of behavioral disclosure. 'Get' implies a read-only operation and the description lists the data types returned, but it doesn't disclose that an aggregated call may return a large payload spanning four data sources, nor any volume or formatting implications. It adds the session-start context but omits size/weight expectations for a multi-source retrieval.

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 waste. The first sentence front-loads the core purpose and components; the second adds a third-person usage directive. Every phrase earns its place, and the most important information (what it returns) comes first.

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

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

With no output schema and no annotations, the description carries substantial burden, and it covers the data components returned and the recommended invocation time. The only gap is a lack of any indication of response format, size, or structure for the aggregated result — minor for this kind of 'grab everything' tool but worth disclosing.

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% — the 'days' parameter is fully documented in the schema with default (7), range (1–90), and a clear description ('Days of work history and commits to include'). The tool description adds nothing about the parameter, which matches the high-coverage baseline of 3 where 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 states a specific verb ('Get'), a clearcapable resource ('full personal context'), and enumerates exactly what it aggregates: playbook, this week's agenda, recent work log, and commits. The phrase 'in one call' explicitly distinguishes this aggregation tool from the individual getters among its siblings (get_playbook, get_agenda, get_work_log, get_commits).

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 at session start' provides an explicit, actionable trigger condition that tells the agent when this tool is appropriate. However, it doesn't name alternatives or state when NOT to use it (e.g., it doesn't say 'for just one component use the dedicated getter'), leaving some routing 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?

The word 'read' clearly signals a read-only operation, and the listed content types define what kind of data is exposed. There is no mention of what happens if no playbook exists or how the response is structured, but for a zero-parameter, side-effect-free tool this is a minimal but adequate 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?

One short, front-loaded sentence with a colon-separated list. Every word contributes either the operation or its scope, with no redundant 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 zero-parameter read tool, this description tells an agent why to call it and what kind of data to expect in the response. It does not specify edge behavior like an absent playbook, but that is not essential for correct tool selection.

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

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

The tool takes zero parameters, so the input schema already fully documents the interface. The description adds meaning about the content returned, which is sufficient given the absence of 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 uses a specific verb ('Read') and resource ('how the user works'), and enumerates the exact facets: approach, bug-fix style, communication preferences. This clearly distinguishes it from related read tools like get_agenda or get_commits, though it does not explicitly name a sibling for 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?

The description implies use when an agent needs to understand the user's working style and preferences. However, it gives no explicit guidance on when to use this instead of get_context or update_playbook, leaving routing slightly 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?

No annotations are provided, so the description carries the behavioral disclosure burden. 'Summary' suggests a read-only operation, and the content types are listed, but the description does not explicitly confirm side-effect-free behavior, permissions, or how the week is resolved beyond what the schema already covers.

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 compact sentence that front-loads the purpose and then lists the three included data categories. It contains no redundant phrases, no filler, and every word contributes to understanding 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?

The tool is low complexity: one optional, fully documented parameter and no output schema. The description names the three output areas. It might have explicitly stated default week behavior or read-only confirmation, but those are minor gaps for an aggregate summary tool.

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

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

The only parameter, week, is already fully documented in the schema: type string, format YYYY-MM-DD, Monday start date, and current-week default. Since schema coverage is 100%, the description adds no meaningful semantic information to justify a score above baseline.

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?

Clear action verb 'get' and explicit resource 'weekly summary' with the exact content categories: agenda stats, work log entries, and commits. This distinguishes it from sibling tools like get_agenda, get_work_log, and get_commits, which each target only one of those data types.

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: call this when a consolidated weekly summary is needed across agenda, work logs, and commits. However, it does not explicitly tell the agent when to prefer this tool over the individual sibling tools, nor does it state any 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?

The verb 'Get' clearly indicates a read-only operation, and the description implies no side effects. However, it does not mention return format, performance, or potential limitations, so it is not fully transparent.

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

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

The description is a single, concise sentence that front-loads the action and resource. It is well-structured and free of unnecessary words.

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

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

With no annotations, no output schema, and minimal parameter explanation, the description lacks critical context such as return format, error handling, and parameter semantics. It is not complete enough for an agent to use effectively.

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

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

The schema provides no descriptions for the 'days' and 'project' parameters, and the tool description does not explain them. An agent cannot infer their meaning or how they affect the query.

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 specifies the action (Get), the resource (recent work summaries), and the source (logged by Claude or hooks). It is distinct enough to be understood without ambiguity.

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

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

The description does not provide any guidance on when to use this tool versus similar siblings like get_weekly_summary or get_commits. It lacks explicit context or selection criteria.

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 of behavioral disclosure. It confirms the operation is a mutation via 'Log', but says nothing about side effects, whether entries are appended to a history, whether invalid commit_hash or agenda_item_id references fail, or any permission requirements. For a write tool with zero annotation coverage, this is a significant 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 a single sentence with the verb front-loaded and no wasted clauses. It is efficient, though 'after completing something' is vague filler that contributes little concrete 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?

Given 5 parameters, an enum, no annotations, and no output schema, the description is far too thin. It omits guidance on what the type values represent, what 'project' refers to, how commit_hash is used, and how agenda_item_id linking behaves — all information an agent needs to invoke the tool correctly.

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

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

Schema description coverage is only 20% — only agenda_item_id is documented. The description does not compensate: it merely echoes the 'summary' concept and gives no meaning or format guidance for type, project, or commit_hash. Four of five parameters are effectively undocumented in both the schema and the description.

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

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

The description names a specific verb ('Log') and a distinct resource ('work summary'), with a timing cue ('after completing something'). It clearly implies a write operation and is naturally distinguishable from the read-oriented sibling get_work_log, though it never explicitly differentiates itself or names 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?

'After completing something' provides an implied trigger for when to use the tool. However, there are no exclusions, prerequisites, or mention of alternatives such as get_work_log for retrieval or add_agenda_item for agenda entries — the routing guidance is inferred rather than stated.

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

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

No annotations are provided, so the description carries full responsibility for disclosing side effects. It implies items are moved but does not state whether they are removed from the source week, duplicated, or how unfinished status is 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, focused sentence with no unnecessary words, and the default is front-loaded after the core 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?

Adequate for a simple mutation, but lacks important context such as the meaning of 'unfinished', side effects on the source week, and any return value. Given no output schema and no annotations, more detail would be expected.

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

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

The schema already gives clear descriptions for both parameters, and the tool description adds a valuable default behavior (last week → this week), improving understanding beyond the schema alone.

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

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

Clearly states the action (move unfinished items) and the source/destination (previous week to current week), distinguishing it from other agenda tools like add_agenda_item or update_agenda_item.

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

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

Provides default behavior (last week → this week) which helps decide when to omit parameters, but does not explicitly contrast with sibling tools or state when to use this tool instead of manual item creation.

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 a meaningful side effect: marking an item done auto-logs work unless log_on_done=false. However, it does not mention other possible side effects, permission requirements, or what happens to fields not explicitly set.

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 primary operation is front-loaded, and the important auto-logging caveat is stated immediately after, making the text easy to scan and process.

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

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

Given the tool has eight parameters, zero schema descriptions, no annotations, and no output schema, the description is not complete enough. It omits several parameter semantics, gives no sibling-tool routing guidance, and does not mention expected return behavior or other consequences of updating.

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

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

Schema description coverage is 0%, so the description must compensate for eight undocumented parameters. It adds real meaning to status, estimate, title, and log_on_done, but relies on 'etc.' and leaves notes, project, and type semantically unexplained.

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

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

The description names a specific verb ('Update'), a specific resource ('an agenda item'), and lists representative fields (status, estimate, title), making the tool's purpose unmistakable. It is clearly distinct from sibling tools like delete_agenda_item, add_agenda_item, and update_playbook by both verb and resource.

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

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

No guidance is given about when to use this tool instead of add_agenda_item, delete_agenda_item, or rollover_agenda. The only conditional note is about log_on_done behavior, which is a side-effect detail rather than tool-selection 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 full burden. It mentions the append behavior but does not disclose whether the operation is destructive (replaces the whole file by default), whether it requires specific permissions, or what the response looks like. For a mutation tool, this is a significant 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 concise, two sentences with no waste. The key usage hint about append is front-loaded, making it easy for an agent to grasp the primary decision point 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?

Given the tool's mutation nature, no annotations, and no output schema, the description is incomplete. It lacks details on default behavior (replacing the file), potential side effects, and any prerequisites. An agent would need to infer or risk incorrect usage.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the append parameter's purpose (add a section without replacing the whole file), which adds meaning beyond the schema's bare boolean. However, it does not explain the content parameter's format or constraints, leaving some ambiguity.

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

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

The description clearly states the tool updates the personal playbook, with a specific verb and resource. It distinguishes itself from siblings like get_playbook by implying a write operation, though it doesn't explicitly name 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 a usage hint for the append parameter, indicating when to use it (to add a section without replacing the whole file). However, it doesn't explicitly state when to use this tool versus alternatives like get_playbook or other update tools, leaving some inference to the agent.

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