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

With no annotations, the description must carry the burden of behavioral disclosure. The verb 'check' implies a safe read-only operation, but the description lacks explicit statements about side effects, error conditions, or what 'status' includes. It does not contradict the lack of annotations; it simply provides minimal safety 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?

The description is a single, focused sentence that conveys the tool's purpose without extra fluff. It is appropriately concise and well-structured, with no wasted words.

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

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

For a simple no-input, read-only status check, the description is nearly complete. The presence of an output schema covers return values, but the description could mention when to use this compared to set_telegram_webhook or what to do with the returned status. Overall, it provides enough context for a straightforward call.

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

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

The tool has zero parameters, and the schema is empty. The baseline for zero-parameter tools is 4, and the description adds nothing contradictory or confusing. No additional parameter explanation is needed.

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 'check' and names the resource 'Telegram bot webhook' and the aspect 'status'. It clearly distinguishes from sibling tools like set_telegram_webhook and poll_telegram_updates, which perform different actions.

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 alternatives. It does not mention that set_telegram_webhook exists for configuring the webhook, nor does it state any prerequisites or exclusions, leaving the agent without clear decision-making support.

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 adds context about the destination directory (10_Inbox) and the return format (8-character issue ID), but does not disclose potential side effects, required permissions, or behavior on failure. Some behavioral traits (e.g., that it's a write operation) are implied by 'create' but not explicitly stated.

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

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

The description is concise and well-structured: a one-line purpose followed by clearly labeled Args and Returns sections. Every sentence contributes useful information without unnecessary verbosity.

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 all three parameters, mentions the return ID, and specifies the destination directory. Since an output schema exists, the return value mention is extra but not necessary. It lacks notes about constraints (e.g., uniqueness) or error handling, but for a simple create tool it is nearly complete.

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

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

Schema description coverage is 0%, so the description must compensate. It provides meaningful descriptions for each parameter: 'Short descriptive name', 'Detailed description', 'Optional list of tags for categorization.' This goes beyond the bare schema and gives clear semantic guidance.

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, resource, and destination: 'Create a new issue in the 10_Inbox directory.' This specific verb+resource+location distinguishes it from sibling tools like read_issue, update_issue, and move_issue.

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 on when to use this tool vs alternatives is provided. The verb 'create' implies usage for new issues, but there are no exclusions or mentions of alternatives. The context from sibling names is not explicitly leveraged.

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

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It mentions returning a 'formatted status summary' and describes the contents, but does not explicitly state whether the operation is read-only, safe, or has any side effects. While 'get' implies a read, the absence of explicit safety or side-effect disclosure keeps this at a minimal viable level.

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

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

The description is concise and front-loaded with the main purpose. The bullet list and 'Returns' line are structured efficiently, with every sentence contributing information. No redundancy or filler is present, making it exemplary in structure.

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 zero-parameter tool with an output schema present, the description is complete. It explains the purpose, the dashboard contents, and the return type. Given the simple nature of the tool, there are no significant gaps in context. The existing output schema likely covers return details, so no further elaboration is needed.

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

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

The input schema contains zero parameters, so there are no parameter semantics to explain. The description adds value by describing the default scope (issues by stage, recent notes), which is more than the schema provides. Baseline 4 is appropriate because the parameter count is zero and the description is clear about what the dashboard includes.

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: 'Get an overview of vault status: issues by stage and recent notes.' It uses a specific verb ('Get') and resource ('vault status') and distinguishes itself from siblings like list_issues or list_notes by providing an aggregated dashboard. The bullet points further clarify the exact 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?

The description provides clear context by framing it as a 'quick dashboard' for checking status, implying use when a broad overview is needed rather than detailed issue/note queries. However, it does not explicitly name alternatives or say when not to use it, so it lacks the explicit exclusions seen in high-scoring examples.

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

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

With no annotations provided, the description carries the transparency burden. It discloses the default stage, accepted aliases, and the newline-separated return format, which adds meaningful behavioral context. However, it omits details about error handling, sorting order, or possible side effects, though these are less critical for a read-only listing tool.

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

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

The description is compact and well-structured with clear Args and Returns sections. It front-loads the main purpose and then provides necessary specifics without any redundant or misleading information.

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

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

The tool is simple with one parameter and an existing output schema. The description covers the essential behavior: what is listed, how the stage is specified, and the return format. No important gaps are evident for a basic list operation.

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

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

The input schema provides only a default with no description or enum. The description fully documents the single `stage` parameter, listing all valid folder names and aliases, effectively compensating for the 0% schema coverage and adding value beyond the structured data.

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 that the tool lists all issues within a specified stage, using the verb 'list' and specifying both the resource ('issues') and the filtering criterion ('stage'). This distinguishes it from sibling tools such as read_issue (single issue) and list_notes (notes).

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 explicitly provide usage guidance or mention alternatives. While the stage argument and its default are explained, it lacks exclusions such as 'for single issue details use read_issue' or 'for full-text search use search_vault,' making the usage context implied rather than explicit.

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

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

No annotations are present, so the description carries the full burden. It discloses the return format (newline-separated filenames) and directory handling, but does not specify whether listing is recursive or how markdown files are identified, leaving some behavioral ambiguity.

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

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

The description is compact, front-loaded with the main purpose, and uses a clean Args/Returns structure with no redundant text.

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 list tool with one optional parameter and an output schema, the description adequately covers core behavior, but lacks explicit detail on recursive listing and sorting, so it is not fully complete.

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

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

The schema has 0% description coverage, but the description fully explains the single parameter: directory path relative to vault root and the None default meaning root directory, adding significant meaning beyond the schema.

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

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

The description states a specific action ('List') with a clear resource ('all markdown files') and scope ('in a directory'), which distinguishes it from sibling tools like list_issues and read_note.

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

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

The description explains the directory argument (relative to vault root, None for root) but does not explicitly contrast this tool with alternatives like search_vault or read_note, leaving usage guidance implied.

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

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

With no annotations, the description carries the full burden. It discloses the allowed stage values and the return type (confirmation message), but lacks details on error handling, reversibility, permissions, or side effects. More behavioral context would be helpful for a mutation tool.

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

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

The description is concise and well-structured, with Args and Returns sections. It is front-loaded with the main purpose, and every sentence provides necessary information without redundancy.

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

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

For a two-parameter mutation tool, the description covers purpose, parameter details, and return value. It could mention edge cases or prerequisites, but given the simplicity, it is sufficiently complete.

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

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

The input schema has no descriptions (0% coverage). The description fully compensates by explaining both parameters: iss_uniq_id is an 8-character unique ID and stage lists all valid values. This goes well beyond the bare 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 action ('Move an issue') and the resource ('to a different stage'), distinguishing it from create/read/update siblings. The verb 'move' is specific 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 usage is implied: use when you want to change an issue's stage. However, it does not explicitly compare to alternatives like update_issue, or state when not to use it. There is no exclusion or alternative reference.

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 of behavioral disclosure. It only states the action (poll and forward) without revealing details like whether this is a continuous or one-shot poll, whether it requires an existing webhook, how errors are handled, or what happens to updates that are already forwarded. This is a minimal disclosure.

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

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

The description is a single clear, front-loaded sentence with no wasted words. It efficiently conveys the primary action and output in a compact form.

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?

Even though this is a simple no-parameter tool (and an output schema exists), the description lacks essential context about the operational environment. It doesn't mention whether a webhook must already be set, how polling is triggered, or what happens to the updates after forwarding. Given the low complexity, this is still a notable gap for agents deciding when and how to invoke it.

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

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

The input schema has zero parameters, so the baseline is 4 per guidelines. The description adds no parameter-specific meaning, but none is needed; it correctly implies the tool requires no inputs and does what it says.

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 ('Poll') on a specific resource ('Telegram') with a defined result ('forward them to local webhook'). It is immediately distinguishable from sibling tools like set_telegram_webhook and check_telegram_webhook, which manage webhook configuration rather than polling for updates.

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 alternatives. The description does not mention prerequisites (e.g., a configured webhook), nor does it exclude situations where polling is inappropriate. Given sibling tools for webhook management, this omission leaves the agent to infer usage context.

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

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

Without annotations, the description must carry the burden of behavioral disclosure. The verb 'Read' clearly indicates a non-mutating operation, and the 'Returns: Full content of the issue file' discloses the output. However, it does not mention potential errors, authentication needs, or what happens if the ID is invalid. This is acceptable for a read operation but leaves some implicit details unaddressed.

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 extremely concise, using a clear structure: a one-sentence purpose statement, then 'Args:' and 'Returns:' sections. Every element earns its place, with no redundancy or padding. The key information is front-loaded, making it easy for an agent to quickly parse.

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 tool with one parameter, the description is quite complete. It states the purpose, explains the parameter, and indicates the return value. The presence of an output schema covers detailed return structure. The main gaps are the lack of explicit error handling descriptions and no mention of authentication requirements, which are minor for a read operation.

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

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

The description provides meaningful detail about the single parameter: 'iss_uniq_id: 8-character unique issue ID.' This goes beyond the bare input schema, specifying the format (8 characters) and confirming its role as a unique identifier. Since schema description coverage is 0%, this compensation is valuable and mostly sufficient, though it could elaborate on the exact character set or source of the ID.

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 is highly specific: 'Read an issue's content by its unique ID.' It clearly states the action (read), the resource (issue), and the access method (unique ID). It naturally distinguishes itself from sibling tools like list_issues (which lists issues) and read_note (which reads notes), making the purpose unmistakable.

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

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

The description implies clear usage conditions: when you have an issue's unique ID and need its content. While it does not explicitly mention alternatives or exclusions, the prerequisite (having the ID) and the outcome (getting content) provide clear context. It stops short of naming contrasting siblings like 'create_issue' or 'list_issues', but the guidance is still sufficient for a simple read operation.

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

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

With no annotations, the description carries the full burden. It discloses that the operation reads and returns full content, which implies a non-destructive action. However, it does not mention error behavior (e.g., missing note), permissions, or any limitations, leaving some behavioral details uncovered.

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 extremely concise, using clear Args and Returns sections. Every sentence contributes necessary information, with no redundant or filler content.

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

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

For a simple single-parameter read operation with an output schema, the description is largely complete: it specifies the input format and return value. It could be slightly richer by noting error cases or constraints, but the simplicity of the tool makes the current coverage adequate.

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

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

The input schema offers only a path string with no description. The description compensates fully by explaining that path is relative to the vault root and provides a concrete example. This adds significant meaning beyond the schema.

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

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

The description clearly states 'Read any note from the vault,' using a specific verb and resource. It distinguishes itself from sibling tools like read_issue (read an issue) and list_notes/search_vault (which list or search rather than read full 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?

The description implies usage when you need to retrieve the full content of a specific note given its path. However, it does not explicitly mention when to use this tool over alternatives like list_notes or search_vault, nor does it provide 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?

With no annotations, the description carries full burden. It discloses the auto-detection logic (regex metacharacters trigger regex search, otherwise case-insensitive keyword search) and the return format ('filepath:linenum: content'). It does not mention permissions, performance, or edge cases, but the core behavior is well covered.

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

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

The description is concisely formatted with a short top-line purpose, bullet points for search detection, and a clear args/returns structure. Every sentence earns its place with no redundancy or fluff.

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

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

The description provides essential information: purpose, search type detection, parameter meaning, and return format. Minor gaps include whether search is recursive across subfolders and whether regex search is case-sensitive. These are not critical for a simple tool but keep it from a perfect score.

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 only provides a query string with no description. The description adds semantics by defining query as 'Search term or regex pattern' and explains how it affects behavior (regex vs keyword). This fully compensates for the 0% schema coverage.

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

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

The description opens with a clear verb and resource: 'Search through all .md files in the vault.' This is specific and distinguishes it from sibling tools like read_note (reading a single note) and list_notes (listing notes). The scope is explicit (all .md files).

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: searching across all markdown files, with automatic regex vs keyword behavior. However, it does not explicitly mention when to use this tool over alternatives like read_note or list_notes, or provide exclusions. It implies usage but lacks direct comparative guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Set', implying a mutation, but does not state whether this overwrites an existing webhook, requires authentication, or has any irreversible effects. This lack of detail is a significant gap for a mutation tool.

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

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

The description is a single concise sentence that is direct and easy to read. It avoids redundancy and is appropriately sized for a simple setter, though it lacks additional context that could be expected.

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 (one parameter) and presence of an output schema, the description is not entirely insufficient. However, it omits usage guidance and behavioral details that would help an agent decide when to invoke this tool, especially with related sibling tools available.

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

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

The schema has a single required parameter 'url' with no description (0% coverage). The description clarifies that this is the webhook URL, but does not explain any constraints like HTTPS requirement or format. It adds minimal meaning beyond the parameter name, so it partially compensates for the lack of schema descriptions.

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

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

The description 'Set the Telegram bot webhook URL' clearly states the specific action (set) and resource (Telegram bot webhook URL). It distinguishes itself from sibling tools like 'check_telegram_webhook' (checks) and 'poll_telegram_updates' (polls), making its 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?

No guidance is provided on when to use this tool versus alternatives such as 'check_telegram_webhook' or 'poll_telegram_updates'. The description does not mention any prerequisites, side effects, or contexts where setting a webhook is appropriate.

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

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

With no annotations provided, the description takes on the full burden and does disclose key behavioral traits: the append parameter explicitly says it appends to the end of a file versus replacing entirely, and the return value is a confirmation message. It lacks detail on failure modes or permissions, but the core behavior is well covered.

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

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

The description is concise and well-structured with a one-sentence summary, a bulleted Args list, and a Returns line. Every sentence provides necessary information without redundancy or fluff.

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

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

The tool is simple, and the description covers the main purpose, all parameters, and return type. An output schema exists, so detailed return values are not needed. It lacks explicit edge-case handling or prerequisites, but for a straightforward update tool, the description is sufficiently complete.

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

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

Schema description coverage is 0%, so the description fully compensates by explaining each parameter: iss_uniq_id is an 8-character unique ID, content is the new content to write or append, and append clarifies the append-vs-replace behavior. This adds meaning well beyond the raw 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 immediately states 'Update an issue's content by its unique ID', using a specific verb and resource. It clearly differentiates from sibling tools like create_issue, read_issue, and move_issue by focusing on updating existing content via unique ID.

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

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

The description clearly implies when to use the tool (to update an issue's content), but it does not explicitly mention alternatives or exclusions. Since the purpose is unambiguous and the context is clear, it earns a 4 rather than a 5.

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