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

With no annotations, the description carries the burden of behavioral disclosure. It discloses that comments are customer-visible by default and explains the author_kind distinction. It does not mention permissions or success feedback, but for a simple write operation this is adequate 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?

The description is three concise sentences with no filler. It front-loads the purpose, then adds differentiation and usage guidance. Every sentence contributes to 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?

For a simple task with no output schema and no annotations, the description covers the essential context: purpose, customer visibility, and author semantics. It does not explain the exact return value or prerequisites, but these are not critical for this tool's usage, and the schema covers parameter details.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the practical use of author_kind (relaying user words vs. AI's own) and clarifying that comments are customer-visible by default, which aligns with the is_internal parameter. This goes slightly beyond the 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 clearly states the tool's action: 'Add a comment to a task's discussion thread.' It uses a specific verb and resource, distinguishing it from the related work notes tool by contrasting comments with the progress journal.

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 contrasts this tool with work notes, clarifying when to use comments vs. the alternative. It also provides specific guidance on when to set author_kind to 'human' versus 'ai', making usage straightforward.

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 key behaviors: append-only ('Notes are append-only and never overwrite each other'), automatic timestamping, and the author_kind distinction. This goes beyond simple mutation and informs the agent about side effects, though it omits error/return behavior.

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

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

Three sentences, front-loaded with the primary purpose, then usage guidance, then a key parameter rule. Every sentence adds value and nothing is redundant.

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

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

The description covers purpose, usage, append-only behavior, and author_kind semantics, which is strong for a simple tool with full schema coverage. It lacks explicit return-value or error details, and is_internal is only in the schema, so it is not fully complete but very close.

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% with descriptions for all parameters. The description adds meaningful nuance for author_kind ('ONLY when you are relaying a note dictated by the human user') and provides an example note for context. Other parameters are sufficiently documented by the schema, so a baseline-3-plus 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 leads with a specific verb and resource: 'Append a timestamped work note (status update) to a task's activity log.' This clearly differentiates it from siblings like add_comment or log_time by emphasizing it as a progress/status record for future sessions.

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 ('Use this to record progress so a future session can pick up where you left off') and includes a conditional rule for author_kind. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a full 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses the domain model and a required precondition (customer_id), but does not describe return value, side effects, permissions, or error behavior. 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?

The description is three focused sentences. It front-loads the action ('Create a new product') and adds only relevant conceptual and lookup guidance without unnecessary filler.

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

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

For a create tool with 4 parameters, complete schema descriptions, and no output schema, the description provides sufficient context about the product–customer relationship and required fields. It would benefit from mentioning return behavior or error cases, but these are not critical given the schema coverage.

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%, providing the baseline of 3. The description adds practical semantic value by explaining that every product belongs to a customer, customer_id is required, and how to find customer IDs via list_products, going beyond the schema's field labels.

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 creates a new product, and adds context that products are top-level containers for projects, which distinguishes it from sibling tools like create_project. The verb-resource pair 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 description explains when to use this tool (creating a top-level container) and provides explicit guidance on required customer_id, including using an internal/own-company customer for internal work. It also directs users to list_products for finding customer IDs, though it does not explicitly contrast with create_project.

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. It discloses that a new project is created, states the inheritance behavior for sub-projects, and mentions the return value. It doesn't cover permission requirements or error conditions, but the core behavioral traits of a create operation are adequately disclosed.

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 the primary action front-loaded in the first sentence. The second sentence packs crucial conditional logic without waste. Every phrase earns its place, maintaining clarity without unnecessary elaboration.

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 creation tool with no output schema, the description is complete: it covers required vs optional parameters, the top-level/sub-project distinction, return value, and references sibling tool list_products for ID lookup. Minor gaps like explicit conflict handling (e.g., setting both product_id and parent_project_id) are implied but not stated, but overall it suffices for an agent to act 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% with each parameter documented, but the description adds cross-parameter logic: product_id is required for top-level, omitted for sub-projects, and inheritance from parent_project_id. This goes beyond individual parameter descriptions and clarifies the relationship, adding significant value.

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 'Create a new project' with a specific verb and resource. It distinguishes from sibling tools by focusing on project creation and provides meaningful detail about top-level vs sub-project semantics, making its 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 explains when to use the tool and how to configure it: top-level projects require product_id, sub-projects inherit from parent and omit product_id. It also references list_products for finding IDs. While it doesn't explicitly mention alternatives like update_project, the context is clear enough for an agent to decide when to invoke it.

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 states the core creation behavior and the return value, but does not disclose validation rules, permission requirements, default status, or other side effects. This is minimal but not misleading.

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 short sentences with no filler, front-loading the core action and then stating the return value. 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?

The schema fully documents all parameters, required fields are explicit, and the description provides the return value in the absence of an output schema. It could add operational context like default status or validation behavior, but the essential calling information 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?

Schema description coverage is 100%, so all 10 parameters are already documented in the input schema. The description adds no extra parameter-level meaning, so the baseline score 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 uses a specific verb and resource: 'Create a new task in a project,' and explicitly states the return value ('Returns the created task with its ID'). This clearly distinguishes it from siblings like create_project and 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 implies that this tool is for creating new tasks in a project, but it does not provide explicit when-to-use guidance or mention alternatives such as update_task for modifying existing tasks. The context is clear but the routing around 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?

No annotations are provided, so the description carries the burden. The verb 'Get' implies a read-only operation, and the description adds context about the return payload (linked projects, team members, statistics). However, it does not disclose potential errors, authorization requirements, or any side effects, which would be useful.

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 one concise sentence that directly conveys the purpose and expected return content without unnecessary fluff. It is front-loaded and effectively communicates the tool's function.

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, no output schema, no annotations), the description is adequately complete. It specifies the key return components (linked projects, team members, statistics) which helps set expectations, though it omits edge-case behavior or explicit usage context.

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 already provides 100% coverage for the single parameter product_id with a clear description. The tool description does not add further semantics about the parameter, and none is needed because the schema adequately defines 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 uses a specific verb ('Get') and resource ('product'), and differentiates from list_products by emphasizing 'specific product' and enumerating the returned details (linked projects, team members, statistics). This clearly distinguishes it from the get_project and list_products 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 implies use for retrieving a single product (via 'specific product'), but does not explicitly name alternatives like list_products or provide when-to-use versus when-not-to-use guidance. It gives context but lacks explicit exclusions.

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

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

With no annotations, the description carries the full burden. It states only that the tool fetches details and lists fields, but it does not disclose behavior around not-found errors, permissions, or any side effects beyond being a read operation. However, the nature of 'get' makes it clearly non-destructive.

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 concise sentence with no filler, completely 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?

For a simple one-parameter get tool without an output schema, the description provides the key information: what it does and what details are included. It could mention return format or error handling, but the core is 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?

The schema fully documents the only parameter (project_id) with a clear description, so the description adds no additional semantic value. 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 uses a specific verb ('Get') and identifies the resource ('specific project') and the key output components ('name, description, status, and task statistics'), clearly distinguishing it from sibling tools like list_projects or create_project.

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

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

The description implies usage for a single project via 'specific project', but it does not explicitly mention when to use this instead of list_projects or alternatives. No exclusions or conditions 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?

Since no annotations are provided, the description itself must convey behavior. It clearly indicates a read operation (via 'Get') and lists the returned fields, which is useful. However, it does not disclose error behavior (e.g., 404 on missing task), permission requirements, or any potential side effects, leaving gaps in full behavioral transparency.

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

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

The description is a single concise sentence that leads with the verb and resource, directly states the purpose, and lists the specific information returned. There is no redundant or extraneous 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?

Given that the tool has only one parameter and no output schema, the description adequately conveys what the user gets by listing the returned components. It lacks details on edge cases (e.g., missing task, authentication) but is sufficiently complete for a straightforward retrieval tool.

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

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

The input schema already provides a complete description for the single parameter task_id ('The ID of the task to retrieve'), so the tool description adds no additional semantic meaning. With 100% schema coverage, the baseline score 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 action ('Get'), the resource ('specific task'), and enumerates the returned information ('description, acceptance criteria, time entries, and status'). This unambiguously distinguishes it from sibling tools like list_tasks (which lists tasks) and get_project/get_product (which target 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 retrieving details of a single task, but it does not explicitly state when to use it over alternatives like list_tasks or search_tasks. It also does not mention any exclusions or prerequisites beyond the obvious 'need a task ID.'

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 burden of disclosing behavioral traits. It does not state whether links are idempotent, whether it overwrites existing links, what happens if the project is already linked, or what the response looks like. The description is too sparse to convey any side effects, permissions, or other operational details.

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, front-loaded with the action, and contains no filler. It is concise, but slightly under-specified for the broader context, making it somewhat too terse. Still, it earns its place and is well-structured for a simple linking operation.

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

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

There is no output schema and no annotations, so the description must compensate by explaining what the tool returns or how it behaves. It only states the action without addressing outcomes, error conditions, or the effect on existing relationships. For a tool that modifies an association, this is a significant gap.

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

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

The input schema already provides descriptions for all three parameters (product_id, project_id, is_primary), achieving 100% schema coverage. The description itself does not add further meaning beyond the schema, so a baseline score of 3 is appropriate. No additional parameter clarification 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 clearly states a specific action: linking an existing project to a product. It uses a precise verb ('link') and identifies both the object and the target, distinguishing it from sibling tools like create_project, create_product, or update_project. No ambiguity about the tool's core function.

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

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

The description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or constraints. There is no mention of when linking is appropriate, whether the project/product must already exist, or any exclusions. For a tool that associates two existing entities, this leaves the agent with little context for decision-making.

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

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

With no annotations, the description carries the burden. It adds context about authentication scope ('accessible to the authenticated user') and the nature of products as containers, but does not disclose pagination, sorting, or result structure. For a simple list operation, 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?

Two sentences, front-loaded with the primary purpose, and the second sentence adds useful domain context. No redundant information.

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

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

For a tool with one optional parameter and no output schema, the description gives sufficient context about the resource and scope. It could mention pagination or result format, but the simplicity of the tool makes it 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?

The schema provides 100% coverage for the single 'status' parameter with a clear description. The tool description adds no additional parameter context, but none is needed. 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 the verb+resource: 'List all products accessible to the authenticated user.' It explicitly distinguishes products as 'top-level containers for organizing related projects,' differentiating from sibling tools like list_tasks and list_projects.

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 by naming the function, but does not explicitly state when to use it versus alternatives like get_product or create_product. No when-not or alternative recommendations provided, leaving the agent to infer from the name alone.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It adds useful context by stating that it lists projects accessible to the authenticated user and specifies the return fields (names, IDs, status, task counts). However, it does not explicitly confirm read-only behavior, mention pagination, sorting, or any rate limits, leaving some transparency gaps. This is a modest but not exhaustive disclosure profile.

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

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

The description is two sentences long, front-loaded with the core purpose, and contains zero extraneous information. Every word contributes meaning: scope, return fields, and access context. This is an exemplary concise description.

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

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

For a low-complexity list tool with two optional parameters and no output schema, the description covers the essential points: what it lists, for whom, and what it returns. It does not mention pagination or sorting, which are common for list tools, but given the simplicity and the fact that the return fields are named, it is sufficiently complete. A score of 4 reflects that it meets the needs without over-specifying.

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 100% description coverage for both parameters (status and parent_id), so the description does not need to compensate. The description itself adds no extra parameter details beyond what the schema already provides, which matches the baseline score of 3 for full 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 uses a specific verb ('List') and resource ('projects') with clear scope ('accessible to the authenticated user'), and distinguishes itself from sibling tools like list_tasks and get_project by focusing on project listing with project-specific fields. It is unambiguous and immediately tells the agent 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 provides clear context for when to use the tool: it lists all projects the user can access. It does not explicitly mention alternatives or exclusions (e.g., 'for a single project, use get_project'), but the context is sufficient for an agent to infer typical use cases. A 4 is appropriate because the context is clear, though no alternatives are named.

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 burden. It explicitly calls out the default compact row shape, lists the exact compact fields, and explains the verbose:true switch for full fields. This is meaningful return-format transparency for a read-only list operation. Pagination or rate limits are not mentioned, but nothing suggests hidden side effects.

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 default behavior and the verbose alternative are front-loaded, and both field lists are presented compactly. 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 3-parameter list tool with no output schema and no annotations, the description covers the required project_id, the default compact representation, and the full-field verbose alternative. The main missing context is pagination or ordering behavior, but this is unlikely to block correct use for typical calls.

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 already documents all 3 parameters with 100% coverage. The description adds value by enumerating the default compact output fields and clarifying what verbose:true changes, effectively compensating for the missing output schema. The status filter nuance is already well covered in 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?

States a specific action and scope: 'List all tasks for a specific project.' The plural 'all tasks' plus the project-scoping clearly differentiates it from get_task (single task) and search_tasks (cross-project search) without needing to name 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?

The description implies the main use case—enumerating tasks for one project—but does not explicitly say when to prefer this tool over search_tasks or get_task, nor when not to use it. No exclusions or alternatives 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does add one meaningful behavioral trait: 'This triggers a real-time notification showing time was logged.' However, it doesn't mention permissions, reversibility, or effects on task status, leaving significant behavioral gaps.

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 long and immediately states the core action. The second sentence adds a relevant side-effect without any unnecessary fluff. Every word contributes value and the structure is ideally 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 is simple with fully documented parameters, but it lacks usage guidance, output details, and deeper behavioral context. The description explains the notification side effect but doesn't cover when to use it or what the response contains. Given the simplicity, a score of 3 reflects adequate but incomplete context for an agent.

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 100% coverage of parameter descriptions, so the schema handles the meaning of task_id, minutes, date, and notes. The description adds no additional parameter-level detail beyond what the schema already states, meeting the baseline expectation.

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: 'Log time spent on a task.' It uses a specific verb and resource, making the primary purpose unambiguous. However, it doesn't distinguish itself from the sibling tool 'quick_log', which likely serves a similar quick-logging purpose.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'quick_log' or 'start_working'. No context, prerequisites, or exclusions are given. Users are left to infer the appropriate use case from the tool name alone.

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

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

No annotations are provided, so the description carries the full burden. It discloses the three main side effects (creates a task, marks it done, logs time) but does not go deeper into specifics like permission requirements, reversibility, or what happens to optional fields. This is adequate but minimal for a composite operation.

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 long, front-loaded with the primary purpose, and every word earns its place. It clearly states the composite behavior and the ideal use case without any fluff 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?

Given the tool's composite nature and full parameter schema, the description is nearly complete. It explains the main behavior and when to use it. It could add details about return values or prerequisites, but the absence of an output schema and the clarity of the description keep it sufficient. Slightly incomplete because it doesn't mention that the task is created as 'done' (though that is implied by 'marks it done'), but still strong.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level detail beyond what the schema already explains; it only frames the overall purpose. It does not explain how optional fields like notes, description, or acceptance_criteria relate to the composite workflow, but that is not required given full 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 and specifically states what the tool does: 'creates a task, marks it done, and logs time in one call.' This distinguishes it from sibling tools like create_task, update_task_status, and log_time by framing it as a composite workflow for completed work. The verb 'quick workflow for logging completed work' is specific and action-oriented.

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 usage context: 'Ideal for recording work that has already been completed.' This implies when to use it (for completed work) and contrasts with the alternative of using separate tools (create_task, log_time, etc.). It does not explicitly name alternatives or say when not to use it, but the context is strong enough.

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 and does a solid job: it discloses matching fields, output row shape, ranking order (title matches, then description, then recency), and the verbose option. It stops short of noting empty-result behavior or other edge cases, but the core behavioral contract is well communicated.

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 carry all essential information with no filler. The main purpose is front-loaded, and the second sentence packs output details, ranking, and the verbose switch into one efficient, readable unit. 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?

Given no output schema, describing the exact compact row fields is essential and well handled. The description also covers ranking and the verbose toggle. The main gap is that 'full rows' fields are not enumerated and no usage recommendation is given for choosing between compact and verbose output, but the tool is still safely invocable.

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 covers all 7 parameters at 100%, so the baseline is 3. The description adds value beyond the schema by explaining how query matches are ranked and what verbose:true changes, which directly informs parameter usage. It does not repeat parameter descriptions, appropriately relying on 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 a specific verb ('Search'), identifies the resource ('tasks'), and scopes the operation ('across all projects by title or description'). It also details the output format and ranking behavior, making the tool's purpose unmistakable even without inspecting the schema.

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

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

The description clearly implies use for finding tasks by text across projects, and the 'across all projects' scope helps distinguish it from more narrow listing tools. However, it does not explicitly name any alternative sibling tool (e.g., list_tasks) or state when not to use this tool, leaving routing to inference.

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

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

With no annotations, the description carries the full burden. It discloses that the operation is an overwrite of a single pinned block, that this context is read first on restart, and that author_kind should be 'human' only when relaying user words. It stops short of detailing edge cases (e.g., missing task), but the core behavior is transparent.

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

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

The entire description is two sentences. The first covers purpose and content; the second provides timing and parameter conventions. Every clause earns its place, with no filler or repetition of schema details.

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 setter with three well-documented parameters and no output schema, the description covers the vital aspects: what the tool does, what the context contains, when to invoke it, and how to set author_kind. It lacks only minor edge-case information, but is otherwise complete for an agent to use confidently.

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 above by specifying the intended content of the context string (state/next/look) and giving a concrete rule for author_kind ('human' only when relaying user words; default 'ai'). This adds practical semantics beyond the 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 opens with a specific verb+resource: 'Set (overwrite) the task's resume context'. It then clarifies exactly what that context contains (current state, done, next, where to look) and distinguishes the tool from siblings by explaining the cold-restart read behavior. This leaves no ambiguity about the tool's unique function.

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

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

Explicit timing guidance is given: 'Update it at the end of a work session' and the tool is described as the first thing read on cold restart, which anchors its role in the workflow. It doesn't name specific sibling alternatives, but the dedicated purpose is so clear that the usage context is effectively established.

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 a key behavioral trait—that the action notifies other team members who is working on the task—but lacks details on edge cases (e.g., idempotency, permissions, or what happens if already marked). For a simple state-change tool, this is adequate but not comprehensive.

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 short sentences that are direct and free of filler. Every word serves a purpose, making it highly concise while still conveying the core action and its social effect.

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

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

For a tool with one parameter and no output schema, the description provides sufficient context: it defines the purpose and the external consequence. It could be slightly improved by adding a note on when to call it (e.g., at the start of work), but overall it is complete for its simplicity.

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 already provides a complete description for task_id ('The ID of the task to start working on'), so the tool description adds no additional meaning. Schema coverage is 100%, which gives the baseline of 3 without requiring extra elaboration.

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 ('Mark'), the object ('a task'), and the state ('actively working'), which is specific and distinguishes it from siblings like stop_working. It also explains the effect (visibility to other team members), leaving no ambiguity about the tool's purpose.

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 one begins working on a task ('Mark that you are actively working'), but it does not explicitly contrast with alternatives such as stop_working or update_task_status. No exclusions or situational guidance are provided, making it average in usage direction.

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

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

No annotations are provided, so the description carries the full burden. It discloses key behaviors: marking the task as stopped, optionally appending a note, overwriting the resume block, and recording both as author_kind="ai". This goes beyond the schema and provides meaningful transparency, though it omits details like permissions or reversibility.

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, front-loaded with the primary purpose, and every clause earns its place. It is concise without sacrificing important behavioral details.

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

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

For a tool with 3 parameters and no output schema or annotations, the description covers the main action, optional state-capture behaviors, and author attribution. It lacks explicit mention of preconditions (e.g., must be currently working on the task) or return values, but these are not critical for a stop action and the description is otherwise 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 100%, so the baseline is 3. The description adds value by explaining that note is 'appended' and resume_context is 'overwritten', and that both are recorded as author_kind="ai". This clarifies the behavioral effect of the parameters beyond their 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 clearly states the tool's function: 'Mark that you have stopped working on a task (break or switching tasks).' It identifies the specific verb (stop working), the resource (task), and distinguishes it from sibling tools like start_working. The optional state-capture details further clarify its role.

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 usage context: it is for stopping work on a task, whether for a break or switching tasks. It also explains when to use the optional note and resume_context parameters. However, it does not explicitly mention alternatives like add_work_note or set_resume_context for cases where only those actions are needed.

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

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

No annotations are provided, so the description carries the full burden of explaining behavior. It only states the action without disclosing whether updates are partial, what is returned, or any side effects.

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 gets straight to the point. It avoids unnecessary words and clearly says what the tool does.

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 description is minimal but sufficient for a simple update operation, especially with full schema descriptions. However, it lacks any mention of the return value or update semantics, and there is no output schema.

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

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

The input schema already provides descriptions for all four parameters (100% coverage), so the description adds little beyond restating three of the fields. It does not clarify the required project_id parameter or the meaning of enum values.

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 with a specific verb ('Update') and resource ('project details'), and lists concrete fields (name, description, status). This distinguishes it from sibling tools like list_projects or create_project.

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

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

The description provides no guidance on when to use this tool relative to alternatives. It does not mention any prerequisites, conditions, or alternative tools for updating projects.

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 without mentioning side effects (e.g., blocked_by replaces the full set), permission requirements, or reversibility. This is a significant gap for a mutation tool with 11 parameters.

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?

Single sentence with no fluff, front-loading the primary purpose. However, it is under-specified for the tool's complexity, so it scores slightly below the maximum for conciseness.

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

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

For a tool with 11 parameters and no output schema, the description is too sparse. It does not explain the scope of updatable fields, behavior nuances (like replacement semantics for blocked_by), or any constraints beyond what the schema provides. An agent would need to rely entirely on the schema, which is not sufficient for effective selection and 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 baseline is 3. The description lists a few example fields, which is redundant with the schema but does not add new semantic information about parameter usage or constraints.

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 (update) and resource (task), and lists example fields (title, description, estimates, acceptance criteria), distinguishing it from sibling tools like create_task and update_task_status. The purpose is unambiguous.

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

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

No guidance on when to use this tool versus alternatives such as update_task_status. Does not mention that status updates have a dedicated tool, or any conditions or prerequisites for use.

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 goes beyond the basic mutation by noting that a real-time notification is triggered and that a derived status may differ from the explicitly set one, which are meaningful side effects. It does not cover permissions or reversibility, but the most important behavioral nuances are disclosed.

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 wasted words. The action is front-loaded, followed by the notification side effect and then the important derived-status caveat. Every sentence adds necessary information.

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

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

For a three-parameter update tool with full schema coverage, the description is largely complete: it covers the core action, side effects, and the key edge case of derived status, while pointing to get_task for the effective values. It does not describe the return value, but there is no output schema and none is strictly necessary for a status update; a brief note on permissions would make it 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the distinction between the settable status and the derived status, and by pointing to effective_status/status_reason on get_task. It does not discuss blocked_reason, but the schema already fully documents that 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 states a specific verb ('Change'), a clear resource ('status of a task'), and enumerates the allowed statuses, so the tool's purpose is immediately obvious. It does not explicitly distinguish itself from the sibling 'update_task', which is a general-purpose update tool, so it stops short of a 5.

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

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

The description implies this tool is for changing task status and warns about derived status differing from the set value, which is useful context. However, it does not explicitly say when to use this tool versus the sibling 'update_task' or any alternative, nor does it mention prerequisites or exclusions.

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