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

Annotations already convey that this is a non-read-only, idempotent write (readOnlyHint=false, idempotentHint=true). The description adds mild behavioral context by noting the action must be user-confirmed, but it does not disclose the persistence/commit effect, failure modes, or expiry behavior beyond what the schema already says about previewToken. There is no contradiction with annotations.

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

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

The description is a single sentence with no unnecessary words and leads with the action verb 'Apply'. It is concise and well structured, though it is slightly too terse to carry much orientation value beyond the high-level purpose.

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 detailed input schema and presence of an output schema cover the mechanical details, and annotations cover safety traits. The description, however, only implies the workflow position (after user confirmation, related to prepare_ai_coach_care) rather than stating it, so the contextual picture is adequate but incomplete.

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

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

Schema description coverage is 100%, so all five parameters are already fully documented, including the previewToken's origin and 60-second validity. The description adds no new parameter-level meaning, so the high-coverage baseline of 3 applies.

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

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

The description identifies a specific verb ('Apply') and a specific resource ('care action'), and adds a meaningful condition ('that the user confirmed in the dashboard'). It is clear, but it does not explicitly distinguish itself from siblings like prepare_ai_coach_care or set_ai_coach_care_confirmation, so it misses the full 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?

The phrase 'confirmed in the dashboard' implies that this tool should be used only after the user has confirmed a care action, and the schema's previewToken description references prepare_ai_coach_care. However, the description itself provides no explicit when-to-use or when-not-to-use guidance, nor does it name 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?

Annotations already mark destructiveHint=true and readOnlyHint=false, but the description adds meaningful behavioral context: the delete is recoverable, user confirmation is required, and note_confirmation_denied indicates the user declined. This goes well beyond the structured annotations.

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

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

Two sentences: the first states the action and recoverability, the second states the user-confirmation behavior and a key error signal. No wasted words; important information is front-loaded.

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

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

Given the full parameter schema, annotations, and the explicit handling of user confirmation and the declined outcome, the description provides everything an agent needs to invoke and interpret the call correctly. No output schema exists, but the key result states are covered.

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

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

Schema description coverage is 100%, so the schema already documents locale, noteId, and idempotencyKey. The description does not need to add parameter details and does not substantially expand on them.

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

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

The description uses a specific verb and resource: 'Move one memo in AI Coach to the trash (recoverable)'. This clearly distinguishes delete_ai_coach_note from sibling read/write/list/search tools, and the 'one memo' wording signals single-item scope.

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

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

It gives explicit usage context: ask the user first unless they requested deletion, and AI Coach also performs its own on-screen confirmation. It does not explicitly name alternative tools or state when not to use this tool, but the deletion-focused context is clear.

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

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

Beyond the readOnlyHint annotation, the description discloses ordering (newest first), returned fields, the absence of full body content, and read-only semantics. Since there is no output schema, this field projection is valuable behavioral information.

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: purpose and ordering first, return fields and the read alternative second, group filtering third. No wasted words.

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

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

For a read-only list tool with no required parameters and a fully documented schema, the description covers what is returned, ordering, filtering, and the safe read-only nature. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents group, limit, locale, and offset. The description repeats the group empty-string behavior but does not add meaning beyond the parameter descriptions.

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

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

Description states the specific action (list), the resource (the user's memos in AI Coach), and the result format (newest first with noteId, title, modified time, size, group, excerpt). It also explicitly distinguishes itself from read_ai_coach_note by saying it does not return the full body.

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

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

The description gives clear context: use this to list memos, use read_ai_coach_note for full content, and pass group/empty string to filter. It does not explicitly contrast with search_ai_coach_notes, but the list-vs-search distinction is reasonably inferable from the wording.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description reinforces the read-only nature. It adds that the tool opens an interactive dashboard, but provides no further behavioral details such as whether it changes UI state or requires any special conditions.

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 that states the action and resource clearly, followed by a useful 'Read-only' marker. There is no wasted wording.

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 viewer with one optional parameter, an output schema, and read-only annotations, the description is mostly complete. The only minor gap is that it does not clarify what 'open an interactive dashboard' physically involves or when it should be selected among dashboard-related siblings.

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 fully documents the only parameter (locale) with a BCP 47 pattern and description. The tool description adds no parameter-specific meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: showing the current state of AI Coach desktop mascots and opening an interactive dashboard. It is distinct from sibling tools like show_ai_coach_message or show_ai_coach_file, though it does not explicitly name a differentiating sibling.

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

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

No explicit guidance is given about when to use this tool versus alternatives. The agent can infer it is the dashboard entry point, but the description does not mention exclusions or when to prefer another sibling like refresh_ai_coach_status.

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

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

The description reinforces the readOnlyHint by saying 'Changes nothing' and adds a workflow detail: the user must confirm in the dashboard. That goes beyond the annotation by explaining where the follow-up action occurs. Error/edge behavior is not discussed, but the output schema and annotations cover much of the remaining context.

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

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

Two short sentences front-load the core purpose and the side-effect constraint with no filler. Every phrase earns its place by helping an agent decide when to call the tool and what to expect.

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

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

For a simple read-only tool with no required parameters, a fully documented input schema, an output schema, and annotations, the description is complete enough. An agent has sufficient structured and textual context to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already explains locale, actions, and mascotId; the description adds little parameter-level meaning. The listed 'walk' action is a slightly loose label for the schema enum 'toggle_walk', but the enum remains the authoritative value source.

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 ('Show') and a clear resource (care actions currently possible for a mascot), and it enumerates the action types. The sentence 'Changes nothing; the user must confirm in the dashboard' clarifies that this is a read-only preflight tool, distinguishing it from state-changing siblings like commit_ai_coach_care.

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

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

The description implies when to use it: to discover which care actions are possible before the user confirms. It does not explicitly name alternatives or state exclusions, though 'the user must confirm in the dashboard' hints that confirmation/commit happens elsewhere. This leaves some sibling differentiation 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?

Beyond the readOnlyHint annotation, the description discloses important behavioral details: truncation/pagination handling via offsetBytes and returnedBytes, and the optimistic concurrency contract involving modifiedAt/expectedModifiedAt. This is genuinely additive context, not just restating annotations.

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

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

Four short sentences, each carrying useful information: purpose, pagination rule, concurrency rule, and read-only safety. There is no verbose filler, and the most important action is front-loaded.

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

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

The description covers the key non-obvious behaviors (pagination, modifiedAt handoff) and the read-only nature. Since there is no output schema, the description mentions response fields like truncated, returnedBytes, and modifiedAt, but it doesn't explicitly name the field for the Markdown body itself. Minor gap, but the core calling contract is well specified.

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

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

Schema description coverage is 100%, so the parameters are already well-documented. The description reinforces offsetBytes usage but does not add meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Read') and a specific resource ('Markdown body of one memo in AI Coach'), clearly distinguishing it from list/search (which find notes) and write/delete (which mutate them). The scope is explicit and unambiguous.

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

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

The description gives clear procedural guidance: how to paginate when 'truncated' is true and how to carry modifiedAt forward for later writes. It doesn't explicitly contrast this tool with siblings like show_ai_coach_message or show_ai_coach_file, so it lacks explicit exclusions, but the usage context is clear.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces that with 'Read-only' and the idempotent-sounding 'Re-read'. It adds the dashboard scope but does not describe what the refreshed state contains or how locale affects output; the output schema carries some of that burden.

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 core action and resource, with no filler or irrelevant detail. The 'Read-only' sentence is slightly redundant with annotations but does not hurt at this length.

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 refresh tool with one optional parameter and an output schema, the description covers the essential what and where. It could add a bit more by naming a sibling alternative or explaining when a refresh is needed, but nothing critical 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 description coverage is 100%, and the single optional locale parameter is already documented as a BCP 47 display language. The description adds nothing about parameters, but the schema already handles it, so baseline 3 is appropriate.

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

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

The description names a specific verb ('Re-read') and resource ('AI Coach mascot state'), scopes it to the dashboard view, and explicitly labels it read-only. This clearly distinguishes it from mutation siblings like write_ai_coach_note or commit_ai_coach_care.

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

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

It gives clear context: use this to re-read the mascot state for the dashboard view, and 'Read-only' signals it is a safe status refresh. It does not explicitly name alternatives or state when not to use it, so it stops short of full routing 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?

Beyond the idempotentHint annotation, the description adds valuable behavioral detail: repeats of the same state are not re-announced, making frequent calls safe. It also clarifies that 'succeeded' and 'failed' are terminal and 'idle' removes the display, which is more context than the annotation alone provides. No contradiction with annotations.

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

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

The description is two sentences with no filler. It front-loads the main purpose, then immediately provides the state usage patterns and the important deduplication behavior. Every sentence earns its place and directly helps the agent decide when and how to invoke 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 description covers the essential behavioral contract: what the tool does, when to call it, how states map to scenarios, and why repeated calls are safe. The remaining parameters (locale, mascotId, ttlSeconds) are fully documented in the input schema, and no output schema is provided, so the description is complete for an agent to use 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 coverage is 100%, so the baseline is 3. The description goes beyond the schema by attaching real-world usage semantics to the state values: which states map to task start, user interaction, and completion. It also notes that the label is optional and short, adding practical context not fully captured by the schema.

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

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

The description clearly states the tool's purpose: having the AI Coach mascot act out the agent's current activity with animation and a speech bubble. It uses a specific verb ('report') and resource ('activity to the mascot'), making it distinct from sibling tools like show_ai_coach_message or open_ai_coach_dashboard.

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

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

The description gives explicit guidance on when to call the tool: use 'thinking' or 'working' when starting a task, 'waiting' when needing the user, and 'succeeded' or 'failed' when finishing. It does not explicitly mention when not to use it or name alternative tools, but the call patterns are clearly actionable.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces that with 'Read-only.' It adds meaningful behavioral detail beyond the annotations: case-insensitive substring matching, matching against title and body, and snippet-around-hit return behavior. No contradiction exists between the description and annotations.

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

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

The description is three sentences and every sentence contributes distinct information: search scope, return behavior, and group filtering. It is front-loaded with the core verb and resource, with no filler or redundancy beyond a brief read-only confirmation.

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

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

For a search tool with four fully documented parameters and read-only annotations, the description is largely complete. It explains what is searched, how matching works, and what the response contains at a functional level. Since there is no output schema, a bit more detail about the exact return shape or ordering could help, but the description is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the schema already fully documents all four parameters. The description reiterates group semantics and matching behavior but adds little beyond the schema. It earns the baseline 3 for not being harmful or misleading, but it does not elevate parameter understanding.

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

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

The description uses a specific verb and resource: 'Search the user's AI Coach memos by title and body text (case-insensitive substring).' It clearly distinguishes the search behavior from sibling list/read tools by mentioning snippet-around-hit results. No ambiguity about what the tool does.

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

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

The description gives concrete usage context for the 'group' parameter: search one group only, use empty string for ungrouped memos, and omit to search all. It also states the operation is read-only. However, it does not explicitly compare this tool with alternatives like list_ai_coach_notes or read_ai_coach_note, so it stops short of full when-to-use-vs-alternatives 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?

Beyond the idempotent/destructive annotations, the description reveals that the setting only affects dashboard care buttons while leaving model-requested care untouched. It implies persistence with 'Remember whether,' though it does not spell out that the choice is stored or how it interacts with an existing value.

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 deliver purpose, scope, and an exclusion without redundant phrasing. The main behavior is front-loaded and 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?

For a low-complexity boolean setter with one required parameter, rich schema descriptions, and an output schema, the description covers all essential call context. It states what is affected, what is not, and the mutation's persistence is captured by the schema's 'from then on.'

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 applies. The description adds contextual scope ('dashboard buttons') but does not need to explain skipCareConfirmation or locale because the schema already documents both accurately.

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 (the AI Coach dashboard confirmation choice) and an action ('Remember whether...'), and immediately scopes it to 'dashboard use only.' This distinguishes it from sibling care-execution tools by stating it controls the dashboard's confirmation behavior, not care actions themselves.

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

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

It explicitly says this is 'dashboard use only' and clarifies the when-not: 'care that the model asks for is always confirmed by the user.' Those statements tell an agent when this preference is relevant and prevent it from using the tool for model-initiated care.

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

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

The description adds meaningful behavior beyond the annotations: HTML is sandboxed, the file is read only by the app, and contents are never returned to the model. This privacy/security context is genuinely valuable for the agent when deciding whether to use the tool. The readOnlyHint=false annotation is not contradicted because the tool still opens a UI preview.

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

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

The description is compact and front-loaded: the core purpose appears in the first clause, supported formats follow immediately, and the usage restriction is stated in one clear sentence. There is no filler or redundant material.

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

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

The description provides everything an agent needs to invoke the tool correctly: allowed formats, sandboxing, privacy behavior, and the exact condition under which use is permitted. Even without an output schema, saying contents are never returned to the model prevents the agent from expecting file content as a return value.

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

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

Schema description coverage is 100%, so the schema already documents path, locale, and mascotId. The description repeats the allowed extensions and mentions HTML sandboxing, but does not add meaningful semantics for locale or mascotId beyond what the schema provides. This meets the baseline without exceeding it.

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 precise action ('Open a safe local preview'), the resource ('local file'), and the context ('beside the AI Coach mascot'), and explicitly enumerates supported file types. This clearly differentiates it from sibling show tools like show_ai_coach_message or show_ai_coach_git_graph, which target different content.

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

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

It gives an explicit usage gate: 'Use only for a file the user asked to preview or one created in the current task,' telling the agent when the tool is appropriate and implicitly when it is not. However, it does not explicitly name alternatives such as read_ai_coach_note for cases where the model actually needs the file contents.

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?

Discloses important behavioral traits beyond annotations: the app reads .git locally, never runs git, never touches the network, and the model only receives a small summary rather than the history. This gives an agent confidence about privacy, side effects, and what the action will/won't do.

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

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

The description is front-loaded with the purpose, then covers prerequisites, behavior, and usage conditions. Every sentence adds value and none are redundant with the schema beyond the path emphasis, which is acceptable for such a critical 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?

With no output schema, the description usefully explains what the model receives (a summary of branch/commit/ref counts) and that full history is not exposed. Minor gaps remain around invalid paths or non-repository folders, but the essential information for correct invocation is present.

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

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

Input schema coverage is 100%, and the description mostly re-emphasizes the path requirement already present in the schema. It does not add meaningful semantics for locale or mascotId beyond their schema descriptions, so the baseline 3 is appropriate.

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

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

The description clearly states a specific action and resource: opening the commit graph (branches, tags, merges) of a local Git repository, with a helpful VS Code Git Graph analogy. It also explicitly scopes the tool to 'when the user asked to see the repository history or graph,' distinguishing it from file-viewing and note-manipulation siblings.

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

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

The description provides an explicit trigger condition ('Use only when the user asked to see the repository history or graph') and a clear prerequisite (absolute path of a folder containing .git). This effectively tells an agent when to choose this tool and what input it must have ready.

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

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

The description characterizes the action as displaying transient UI content in the mascot's speech bubble, and annotations already indicate non-read-only and non-destructive behavior. It adds the 140-character limit and plain-text restriction, but it does not clarify whether the message replaces an existing one or auto-dismisses.

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 only two sentences long, with the core action and the key limit front-loaded in the first sentence. The second sentence earns its place by ruling out images and links, leaving no filler or repetition.

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

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

For a simple display tool with one required parameter, the description covers the essential information: what to display, where to display it, and what content is not allowed. The locale and mascotId behavior is fully described in the schema, and the annotations cover the safety profile, so only minor behavioral details such as message replacement or auto-dismissal are missing.

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

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

The schema already documents all three parameters—text, locale, and mascotId—with meaningful descriptions, and the context signals report 100% schema description coverage. The tool description only restates the 140-character plain-text constraint for text, adding no substantial semantic value beyond the schema.

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

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

The description uses the specific verb 'Display', identifies the exact resource ('the AI Coach mascot's speech bubble'), and scopes the action to a short text of up to 140 characters. The closing 'Text only; no images or links' helps distinguish this tool from sibling display tools like show_ai_coach_file and show_ai_coach_git_graph.

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 appropriate usage through constraints like 'short text' and 'Text only; no images or links', which tells an agent this tool is not for media content. However, it never explicitly names alternatives or states when to choose this tool over a sibling, so the guidance remains implicit.

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?

Adds substantial behavioral context beyond annotations: the user confirmation prompt, multi-second latency, storage as a local Markdown file, optimistic concurrency via expectedModifiedAt, and the meaning of note_confirmation_denied. This complements the idempotentHint=true annotation and does not contradict any annotation.

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

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

The description is dense but compact, with the core action and resource front-loaded, followed by mode, grouping, concurrency, and confirmation behavior in logical order. Every clause contributes operational meaning; there is no filler or redundancy.

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

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

The description covers storage location, modes, group creation, concurrency protection, user confirmation, latency, and a specific error outcome. Since there is no output schema, the absence of a success return description is a minor gap, but the tool can be invoked correctly with the information provided.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the purpose of expectedModifiedAt as a guard against overwriting the user's own edits and clarifies mode semantics such as append for large bodies. These additions go beyond the schema's literal parameter descriptions.

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

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

States a specific verb and resource: 'Create, replace or append to a memo in AI Coach.' It further describes the memo as a plain Markdown file visible immediately, and enumerates the three modes. This clearly distinguishes it from read, list, search, and delete 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?

Provides explicit workflow guidance: read an existing memo first and pass its modifiedAt to prevent overwriting user edits. It also gives mode selection advice, including using append for bodies over the per-call limit. It does not explicitly name alternative tools or state when not to use this tool, but the context is clear.

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