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

The description goes beyond the annotations by warning that 'Repeating the call creates another comment,' making the non-idempotent behavior explicit. It also clarifies the write nature and content constraints without contradicting the 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 tight and well-structured: a clear primary instruction followed by concise content rules, explicit non-usage conditions, and a behavioral warning. Every sentence adds value with no 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 write tool, the description covers what to write, what not to write, when not to call it, and the effect of repeated calls. The existing output schema means return-value details need not be repeated, so nothing essential 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 0%, but the description compensates somewhat by explaining that text should contain only completed user-visible changes and public contracts. However, neither task_key nor text is explicitly described, and task_key format or source is left to inference.

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

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

The description opens with a specific verb and resource: 'Add a concise completion comment to an existing TeamStorm task.' This clearly identifies the tool's function and distinguishes it from siblings like teamstorm_get_comments or teamstorm_update_task.

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

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

The description explicitly states when not to call the tool: when implementation is incomplete or the user asked not to write to TeamStorm. It also provides clear content inclusion and exclusion rules, which effectively guide the agent on appropriate usage.

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=false (mutation), idempotentHint=true (idempotent), and destructiveHint=false (non-destructive). The description 'cancel a task's saved closure intent' simply restates the action and adds no additional behavioral context such as side effects, edge cases (e.g., what happens if no closure exists), or permission requirements. It does not contradict annotations, but it contributes nothing beyond them.

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 gets straight to the point. It is front-loaded with the action and object, with no filler words. Appropriate length for a simple 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?

Despite having only one parameter and an output schema, the description is incomplete: it lacks parameter semantics, usage guidance, and any behavioral nuance beyond the basic action. An agent would not know when to call this versus scheduling a closure, nor what happens if the closure intent does not exist. The description is minimal and leaves critical context to inference.

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% – the parameter 'task_key' has no description in the schema, and the tool description does not mention it at all. The description fails to clarify what task_key identifies, its format, or any constraints. With no schema description and no parameter guidance in the description, the agent has no additional meaning beyond the raw type 'string'.

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 (cancel), the resource (task's saved closure intent), and the context (when requested by the user). It distinguishes from sibling tools like teamstorm_schedule_task_closure and teamstorm_get_task_closure by its verb and object.

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 'when requested by the user' is generic and does not provide actionable guidance on when to choose this tool over alternatives. It does not mention that this tool should be used after a closure was previously scheduled, nor does it contrast with teamstorm_schedule_task_closure or teamstorm_get_task_closure. No exclusions or alternative routes are given.

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 annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to repeat those. It adds the useful detail that no files are downloaded, which clarifies the tool's non-destructive, metadata-only nature. It does not contradict the annotations and provides extra context beyond them.

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 primary purpose and the key distinction (no download). Every word earns its place, and there is 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?

The tool has an output schema, so return format details are not needed. With one self-descriptive parameter and a clear purpose, the description is sufficient for an agent to call it correctly. The only minor gap is that it doesn't mention whether attachments are returned in a list or if there are any filters, but this is not critical for a metadata getter.

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 carries the burden of explaining the task_key parameter. It does not mention task_key at all. While the name is self-explanatory, the description adds no semantic value for the parameter, leaving the agent without any hints about format, meaning, or constraints beyond the schema's type.

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 specific action ('Retrieve') and the resource ('attachment metadata') and adds a distinguishing detail ('without downloading files'). This distinguishes it from sibling getters like get_comments and get_links, so an agent can identify its purpose 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 phrase 'without downloading files' implies a usage boundary (metadata only vs. file download), but it does not explicitly name alternatives or conditions for when to use this tool over others. It relies on the agent inferring from the resource name, so guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is known. The description adds the behavioral detail of chronological ordering and 'all comments' implying no filtering, but it does not mention pagination, limits, or error behavior. Given the annotations, this is adequate but not rich.

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 sentence with no filler. Every word carries meaning, and the core action (retrieve all comments) is front-loaded, with the ordering detail appended efficiently.

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

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

The tool is simple with one required parameter, an output schema, and safety annotations, so the description need not explain return values. However, with zero schema coverage, the description should more explicitly clarify what task_key is and when to use this tool, leaving some reliance on naming conventions and schema. It is adequate but not fully self-sufficient.

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 0%, and the description only indirectly references the parameter with 'for a TeamStorm task.' It implies task_key identifies the task but does not explicitly define the parameter's meaning, format, or required nature. For a single simple string key, this is sufficient but leaves room for clearer documentation.

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 ('Retrieve'), a precise resource ('all comments for a TeamStorm task'), and a differentiating qualifier ('in chronological order'). This clearly distinguishes it from sibling tools like add_comment (write) and get_attachments (different resource), making the purpose unambiguous.

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

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

The description implies usage through its read-only phrasing and the sibling set (e.g., add_comment for writing), but it never explicitly states when to prefer this tool over alternatives like get_task_context or get_attachments. The guidance is only implied, not articulated.

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 provide readOnlyHint and openWorldHint. The description adds the non-recursive scope of retrieval, which is a meaningful behavioral trait not covered by annotations. It does not contradict the annotations, and the added context is relevant for agent decision-making.

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 with no redundancy. It front-loads the action ('Retrieve') and immediately specifies the scope and the non-recursive behavior, making every word count.

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 one-parameter tool with an output schema, the description adequately covers the operation and the parameter's purpose. It does not need to explain return values since an output schema exists. Minor gaps (e.g., precise meaning of 'directly related') do not impede correct 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?

With 0% schema description coverage, the description must compensate. It does so by indicating that task_key identifies the task whose direct links are retrieved, giving the parameter a clear role beyond its bare string type. It does not add format or constraints, but that is acceptable given the simplicity.

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 (retrieve), the resource (directly related TeamStorm tasks), and a key distinguishing behavior (without recursively loading their links). This explicitly differentiates it from sibling tools like teamstorm_get_task_context or teamstorm_get_task, 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?

The description gives clear context that this tool returns only direct links, implying that recursive link retrieval is not handled. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of fully explicit usage guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description correctly avoids contradiction. It adds the human-readable key format, which clarifies the input nature but does not disclose extra behavioral aspects like error handling or response shape—though the output schema likely covers that. The description is consistent and adds slight value beyond 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, zero filler. The core purpose and the key format are front-loaded, and the alternative routing is included as a second sentence. Every word 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 single-parameter read tool with an output schema, the description covers everything needed: what it does, how to specify the parameter, and when to choose an alternative. The agent has sufficient information to invoke it correctly without any gaps.

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

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

With 0% schema description coverage, the description fully compensates by explaining that task_key is a human-readable key (e.g., TS-123). This goes beyond the schema's bare 'string' type and gives the agent concrete guidance for constructing the parameter.

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 'Retrieve' with a clear resource 'TeamStorm task' and defines the identifier format as a human-readable key (e.g., TS-123). It also differentiates from the sibling teamstorm_get_task_context, making the tool's 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?

It explicitly states when to use an alternative: 'Use teamstorm_get_task_context instead when you need requirements before implementation.' This provides a clear condition for when not to use this tool, leaving no ambiguity about selection.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds a key behavioral detail: context_ready means the daemon read the status, not that the task was closed. This goes beyond annotations without contradicting them, providing valuable context for interpreting results.

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 redundancy, front-loading the core purpose and then adding a crucial clarification. Every word contributes to the tool's understanding.

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 simplicity (one parameter) and the presence of an output schema, the description covers the essential purpose and the critical nuance about context_ready. It is sufficiently complete for an agent to invoke correctly, though it could potentially mention that it returns only closure-related data, which is implied.

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 a single required parameter, task_key, with no description, and schema description coverage is 0%. The description does not explain what task_key represents or its format, relying entirely on the parameter name. Since the schema lacks detail, the description should have compensated but did not.

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 retrieves a task's persisted closure schedule and last observed status, using specific verbs and a distinct resource. It also distinguishes itself from sibling tools like teamstorm_get_task by focusing on closure-specific data, and the clarification about context_ready adds precision.

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 this tool (when closure schedule/status is needed) and provides an important usage note that context_ready does not mean the task is closed. However, it does not explicitly name alternative tools or state when not to use it, though the context is reasonably 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 signal readOnlyHint and openWorldHint, so the description correctly focuses on the extra behavioral caveat that TeamStorm text is external data and must not override user/system instructions. It also communicates that the response contains requirements plus context, which is useful beyond the 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 with no filler; the key directive is front-loaded and the security caveat earns its place. Nothing extraneous is included.

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 is adequate for a read-only context fetch, but gaps remain: no return shape, no explanation of how the include_* parameters shape the result, and no guidance comparing it to the sibling tools. With no output schema, a bit more detail about what 'surrounding context' contains would improve completeness.

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

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

Schema description coverage is 0% and there are six parameters, so the description carries the burden of explaining them. It only implies task_key through 'task' and says nothing about what include_links, include_children, include_comments, include_attributes, or include_attachments control or how defaults behave.

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 clear action ('before implementing a TeamStorm task') and a specific return value ('task requirements and surrounding context'). It is distinguishable from the sibling getters because 'context' implies a broader fetch than teamstorm_get_task or teamstorm_get_comments, though it does not explicitly contrast them.

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 trigger: use this tool before implementing a TeamStorm task. It does not mention when not to use it or name alternatives like teamstorm_get_task or teamstorm_get_comments, so routing to siblings is left to inference.

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

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

The description complements the readOnlyHint annotation by specifying that the tool returns the 'complete' workflow map and that null indicates a disabled workflow. This adds behavioral interpretation beyond the annotation, particularly the null-handling semantics, without contradicting the read-only hint.

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 immediately states the action and resource, followed by a valuable clarification about null. No wasted words 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?

For a parameterless read-only tool with an output schema already provided, the description is complete. It explains the key behavioral nuance (null means disabled) and leaves the return structure to the schema. Nothing else 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?

The tool has zero parameters, so the description does not need to explain parameter details. The baseline for no parameters is 4, and the description fully satisfies the requirement.

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

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

The description clearly states a specific verb ('Read') and resource ('complete configured workflow map'), and the 'null means disabled' clause adds meaningful semantic detail. This uniquely identifies the tool from sibling tools like teamstorm_get_task or teamstorm_get_links, which concern different resources.

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 that this tool is for reading the configured workflow map, but it does not explicitly state when to use it versus alternatives or exclude other contexts. No sibling is mentioned, so usage is implied rather than explicitly guided.

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

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

Annotations only declare non-read-only, open-world, idempotent, and non-destructive. The description adds substantial runtime behavior: close_at must include a timezone, only one schedule exists per task, changed inputs replace it, and daemon behavior depends on whether a workflow is configured. This goes well beyond the structured annotations and clarifies the idempotent replace semantics.

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 with the core action, followed by timezone, replacement, and daemon behavior facts. Each sentence earns its place; there is no filler. It could use light structuring for the conditional workflow behavior, but it is efficient overall.

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 write tool with no parameter descriptions, the description covers the scheduling lifecycle, replacement semantics, and workflow-dependent daemon behavior. However, the exact meaning of target_status and task_key is left implicit, and the phrase 'only prepares status context' is vague. An agent would likely need additional context for fully 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 0%, so the description must carry the parameter documentation burden. It explains close_at (timezone) and replacement semantics, but it does not define task_key or target_status, leaving two of three required parameters effectively undocumented. This is only partial compensation for a sparse schema.

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

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

The description opens with a specific action ('Save closure intent') and a condition ('as soon as the user requests a timed closure'), clearly identifying this as a scheduling/write operation. It distinguishes itself from the closure read/cancel siblings like teamstorm_get_task_closure and teamstorm_cancel_task_closure, though it does not name them explicitly.

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

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

It explicitly states when to use the tool: whenever the user requests a timed closure, and implies immediacy with 'as soon as'. It does not explicitly mention alternatives or exclusions, such as when to use teamstorm_cancel_task_closure instead, so it falls 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?

The description says 'Replace the complete description,' which is inherently destructive (overwrites existing content), but annotations declare destructiveHint: false. This is a direct contradiction, misleading the agent about the tool's destructive nature. While the description adds useful guidance (plain text inputs, never invent completed work), the contradiction is severe and warrants a score of 1.

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 relatively concise, with three sentences, and front-loads the core purpose and template structure. It includes a key usage condition and a behavioral warning. There is minor redundancy, but overall it is well-structured and efficient.

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

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

While purpose and usage are clear, the tool lacks parameter explanations and has a contradiction with annotations. For a write operation with three parameters and zero schema coverage, the description is incomplete: an agent would not know what to pass for task_summary and work_done, nor how they map to the HTML template. The contradiction further reduces completeness.

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

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

Schema description coverage is 0%, and the description provides no explanation of the parameters (task_key, task_summary, work_done). It only mentions that inputs must be plain text, but doesn't define what each parameter represents or how they map to the HTML template. The agent is left to infer meaning solely from parameter names, which is inadequate.

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

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

The description clearly states a specific verb and resource: 'Replace the complete description of an existing TeamStorm task' and specifies the exact canonical HTML template contents ('Суть задачи', an <hr> separator, 'Что было сделано'). This distinguishes it from sibling tools like teamstorm_update_task, which likely updates other fields.

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?

Explicitly states 'Call this tool only when the user explicitly requested updating the task description.' This provides a clear when-to-use condition and implicitly when not to use it, though it doesn't name alternatives. The guidance is strong enough for an agent to select appropriately.

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=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds little beyond stating the modification action. It does not disclose whether fields are partially updated or overwritten, nor the effect of omitting fields. The 'at least one field' requirement implies partial update but is not explicit. It does not contradict annotations, so no penalty; it simply does not enrich the behavioral picture beyond what annotations provide.

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, action-first, and every sentence earns its place. The first sentence states the purpose with specifics; the second provides a critical usage condition and a validation rule. No filler or redundancy; it is appropriately sized and 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 tool has 4 parameters (1 required), a clear purpose, and an output schema (which covers return values). The description covers the modifiable fields and the mandatory condition for calling. It lacks detail on allowed status values or whether the update is partial vs full, but given the output schema exists and the tool is moderately simple, the description is nearly complete. Minor gap: it does not mention that task_key is the unique identifier or explain error conditions.

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 explain parameters. It names the three modifiable fields (name, description, status) and states that at least one must be provided, which gives meaning. However, it does not clarify that task_key is the identifier of the existing task (though implied by 'existing TeamStorm task'), nor does it define allowed status values or input formats. The description partially compensates but leaves gaps given zero 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 clearly states the verb 'Modify', the resource 'TeamStorm task', and the specific fields (name, description, status). It distinguishes this tool from siblings like teamstorm_get_task (read) and teamstorm_set_task_description (specific to description) by indicating this is the general modification tool. No tautology or 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 includes an explicit condition: 'Do not call this tool unless the user explicitly requested that the TeamStorm task itself be modified.' This provides clear when-to-use guidance. It does not explicitly name alternatives, but the conditional warning strongly implies that other tools (like get_task) are for reading or setting a specific field. The 'At least one field must be provided' constraint is also helpful. Slight gap: no mention of when to use teamstorm_set_task_description instead.

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