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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only restates the action ('Post a comment') and gives use cases, but does not reveal side effects, permissions required, response behavior, rate limits, or any constraints beyond the schema. For a mutation tool, this is a significant gap—similar to the update_drive calibration example.

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 zero fluff. The core action is front-loaded in the first sentence, and the second sentence provides useful usage context. Every word earns its place, making it efficiently scannable for an agent.

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, the schema covers all parameters, and there is no output schema to describe. The description is sufficient for an agent to invoke the tool correctly—it knows the purpose, required parameters from the schema, and the communication context. It does not explain the relationship to list_task_comments, but that is not necessary for executing this 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?

Schema description coverage is 100%, so the baseline is 3. The description does not add any parameter-specific meaning beyond what the schema already provides (e.g., it doesn't clarify isPrivate behavior or contentType usage). It mentions 'task thread' but that relates to the tool's purpose rather than parameter semantics.

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

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

The description states a specific verb and resource: 'Post a comment on a task.' It also lists concrete use cases (report progress, answer questions, hand off work) that make the tool's role clear. This distinguishes it from sibling tools like list_task_comments (read-only) and create_task/update_task (task-level operations), so an agent can immediately identify the correct tool.

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 contextual usage: 'Use to report progress, answer questions or hand off work in the task thread.' This tells the agent when to apply the tool. However, it does not explicitly mention alternatives or exclusionary conditions (e.g., when to use list_task_comments instead), so it stops short of a perfect 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?

Annotations declare readOnlyHint=true, and the description adds useful context beyond that: it names the specific aspects it inspects (configuration existence, target site, storage location). This helps the agent understand what the tool does without side effects. It doesn't describe return format, but that's minor for a read-only diagnostic.

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, information-dense sentence that front-loads the action ('Check') and then enumerates the three key outputs. Every word earns its place; there is zero redundancy or fluff.

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

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

For a parameterless, read-only tool with no output schema, the description fully covers what the agent needs to know: what it does, what it returns conceptually, and that it is safe. The tool's simplicity means 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?

The tool has zero parameters and schema coverage is 100% (empty schema). The description adds no parameter details because none exist. With no parameters to document, this dimension is trivially satisfied; a baseline of 4 applies and the description exceeds it by being clear about the tool's scope.

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 ('Check') and resource ('Teamwork API key configured on this machine'), and enumerates the exact facts it returns (whether configured, site, storage location). This clearly distinguishes it from siblings like whoami or logout, which address different concerns.

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 purpose is self-evident: use when you need to verify API key setup. It doesn't explicitly state when not to use it or mention alternatives, but given no sibling overlaps, the context is clear enough. A slight improvement would be to note it's a preflight check before other calls.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action 'create' without mentioning side effects, return values, required authentication, or idempotency. This is minimal and does not add meaningful transparency beyond the obvious.

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, efficient sentence that is front-loaded with the core action. It avoids unnecessary verbosity, though it borders on tautology by closely mirroring the tool name. Still, it earns its place by specifying the resource context.

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

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

Given the tool has 6 parameters, 2 required, no annotations, and no output schema, the description is severely under-specified. It doesn't mention required fields, return behavior, or any constraints. An agent would need to inspect the schema and make assumptions about the response, which is a significant gap for a mutation 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 provides complete descriptions for all six parameters (100% coverage), so the baseline is 3. The description adds no additional parameter-level context, but since the schema is thorough, this is acceptable.

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 'Create' and the resource 'task inside a task list', which precisely identifies the operation. It distinguishes itself from sibling tools like update_task and list_tasks, 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 by stating the action, but provides no explicit guidance on when to use this tool versus alternatives (e.g., update_task for modifications). It doesn't mention prerequisites or exclusions, so it relies on the agent inferring the context.

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

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

Annotations already declare readOnlyHint=true, and the description aligns with that as a read operation. It adds a little context by indicating the response includes the description and key fields, but it does not detail which fields count as key or mention any other behavioral aspects 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 a single efficient sentence with no filler. The verb and resource are front-loaded, and every word contributes useful meaning.

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 read tool with a readOnly annotation, the description is nearly complete. It does not enumerate all returned fields, and there is no output schema, but the low complexity and clear annotations make this a minor gap rather than a serious deficiency.

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 fully documents taskId with a clear description ('Teamwork task id'), so schema coverage is 100%. The description adds no extra meaning to the parameter, leaving the schema to carry the semantic burden, which warrants the baseline score of 3.

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 ('Fetch') and a specific resource ('a single task'), and mentions what is included ('description and key fields'). It clearly distinguishes this from sibling tools like list_tasks (which fetches multiple tasks) and update_task/create_task (mutations).

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 correct use case: retrieving one task by ID, which differentiates it from list_tasks for bulk retrieval and create_task/update_task for writes. However, it does not explicitly name alternatives or state when not to use this tool.

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 include readOnlyHint: true, so the read-only nature is already disclosed. The description adds that it is chronological and mirrors the widget, providing slight context beyond annotations. However, it does not mention pagination behavior, ordering details, or potential response size, which would be valuable for an 8-parameter tool with no output schema. The description adds some value but not rich behavioral detail.

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

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

The description is two sentences with no filler. The first sentence states the core purpose and scope, the second lists filtering options. Information is front-loaded, and every word earns its place. It is appropriately concise for the tool's simplicity.

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 8 parameters, 0 required, and no output schema, the description covers the main functionality and filter dimensions. It does not describe the return format (e.g., a list of activity objects) or pagination details, but these are partially inferable from the parameter names. Given the tool is a read-only feed and the description provides sufficient context for an agent to invoke it correctly, it is mostly complete, though a brief note on response structure would improve it.

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

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

Schema description coverage is 75% (6 of 8 parameters have descriptions). The description summarizes filters as 'project, user, type or date range', which aligns with projectId, userIds, activityTypes, and since/until parameters already described in the schema. It does not add new meaning beyond the schema; page and pageSize are not mentioned but are self-explanatory from their schema definitions. With high schema coverage, the description adds minimal extra semantic 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 the tool's purpose: 'Chronological feed of recent activity across all projects' with explicit examples (comments, task updates, files, milestones) and mentions it mirrors the Teamwork activity widget. This distinguishes it from sibling tools like list_tasks or list_projects, which target specific entities, making it unambiguous what this 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 context that it's a cross-project activity feed and mentions filterable dimensions (project, user, type, date range). While it doesn't explicitly say when to use it over alternatives, the 'activity feed' framing clearly separates it from sibling list tools. It lacks explicit exclusions or 'use instead' guidance, but the intent is evident.

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, so the tool's non-destructive nature is covered. However, the description adds no behavioral context beyond that—no mention of pagination, rate limits, or any side effects. It simply restates the operation without enriching the agent's understanding of runtime 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?

The description is a single, front-loaded sentence that states the purpose and the output fields. There is no fluff or redundant phrasing; 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 tool has 5 optional parameters and no output schema, yet the description provides no guidance on how to use the parameters or what the response format looks like beyond naming the fields. It does not explain the role of includeClients or includeCollaborators, nor pagination via pageSize. This is inadequate for an agent to call the tool correctly without additional 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 only 40% (emails and search have descriptions; pageSize, includeClients, includeCollaborators do not). The description itself does not describe any parameter or explain how they influence results. With low schema coverage and zero description support, the agent cannot infer the meaning or effect of the undocumented parameters, so this is a critical gap.

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 'Find' and the resource 'users', and even specifies the output fields (id, name, email) and the intended use case (assignees or user filters). This distinguishes it from all sibling tools, none of which target user lookup.

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: 'to use as assignees or in user filters'. It doesn't explicitly name alternatives or exclusions, but the sibling set makes it obvious that no other tool serves this purpose, so the guidance is sufficient.

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 declare readOnlyHint=true, which the description does not contradict. The description adds scoping ('visible to the API key') and pagination ('results are paged') but does not cover rate limits, auth requirements, or return format. Given the read-only annotation, this is acceptable 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 a single sentence with no filler. It front-loads the core purpose and includes the key behavioral detail (pagination) without redundancy.

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

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

For a simple list operation with a full parameter schema, the description covers the essential scope and paging. It does not describe return fields, but given no output schema is present and the tool is straightforward, this is a minor gap. The lack of alternative guidance is more of a usage-guideline issue.

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 four parameters have descriptions. The description does not add additional semantics beyond what the schema already provides, such as default values or format. It merely restates the search functionality already 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 clear verb (list) and resource (projects) with a scope qualifier ('visible to the API key'). The purpose is unambiguous and distinct from sibling tools like list_tasklists, though it does not explicitly name an alternative.

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

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

Provides no explicit guidance on when to use this tool versus alternatives such as 'search' or 'list_tasklists'. The phrase 'Use search to filter by name' refers to the search parameter, not a tool choice, and no exclusions or when-not-to-use 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?

The description is consistent with the readOnlyHint annotation. It does not add extra behavioral details such as pagination behavior or return format, but the annotation already covers the read-only nature. It adds minimal context beyond that.

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

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

The description is a single sentence with no redundant information. It is appropriately concise and front-loaded with the core action.

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

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

Given the tool has three parameters including pagination controls and no output schema, the description is minimal. It does not mention that the tool returns a list of comments or how pagination works. However, for a simple read operation, it might be adequate, but it could be more 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 description coverage is only 33% (only taskId is described). The tool description does not mention the page and pageSize parameters, so it does not compensate for the missing schema descriptions. An agent would not know that page and pageSize are optional pagination controls from the description alone.

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

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

The description uses a clear verb 'Read' and a specific resource 'comment thread of a task', making it easy to distinguish from sibling tools like add_task_comment or get_task. It states exactly 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?

There is no explicit guidance on when to use this tool versus alternatives. It does not mention that add_task_comment is for writing comments, or that get_task is for task details. The usage context is implied but not stated.

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

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

The annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds a small amount of context by equating task lists to 'columns/boards', but it discloses nothing about pagination, ordering, or response 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?

The description is a single, focused sentence that front-loads the core operation and resource. The parenthetical clarification adds immediate value without waste.

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

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

With no output schema and 50% parameter coverage, the description leaves important context missing: how pagination works, what the response looks like, and how search filters results. For an agent to invoke the tool correctly in non-trivial scenarios, additional field-level guidance is needed.

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

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

Schema description coverage is only 50%, with page and pageSize lacking descriptions. The tool description does not compensate by explaining these parameters, their defaults, or their interaction. It only indirectly implies projectId through 'inside a project'.

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'), a specific resource ('task lists'), and a clear scope ('inside a project'). The parenthetical '(columns/boards)' clarifies the domain-specific meaning, distinguishing it from other list-type tools like list_projects or list_tasks.

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

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

No guidance is given about when to use this tool versus alternatives such as list_tasks or get_task. The phrase 'inside a project' implies the projectId requirement, but there is no explicit mention of search or pagination usage nor any exclusion of sibling tools.

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, so the read-only nature is covered. The description adds valuable behavioral context by stating that completed tasks are excluded unless includeCompleted is true, which is a non-obvious default behavior. It also clarifies the scope of the search (across projects or within a specific list), adding 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?

The description is two sentences with no extraneous content. The main purpose and scope are front-loaded, followed by the key behavioral note about completed tasks. Every word earns its place, achieving maximum efficiency.

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

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

Given the tool has 6 parameters and no output schema, the description covers the primary purpose, scope, and a key default behavior (completed exclusion). However, it omits details on pagination (page, pageSize) and response format, which might be necessary for an agent to fully understand how to use the tool. The description is adequate but not exhaustive, especially without an 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?

Schema description coverage is 50% (search, projectId, tasklistId have descriptions; page, pageSize, includeCompleted do not). The description explicitly mentions includeCompleted and its effect, adding meaning beyond the schema. However, it does not address page, pageSize, or pagination, leaving gaps for those parameters. The description partially compensates for the missing schema descriptions but is not comprehensive.

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 'search' and the resource 'tasks', with a scope of 'across projects or within one project/task list'. This distinguishes it from siblings like get_task (single task), create_task, and list_projects/list_tasklists (different resources). The mention of 'search' differentiates it from the generic 'search' tool by specifying task-specific behavior.

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 context on when to use the tool (searching tasks) and its scope (across projects or within a specific project/task list). However, it does not explicitly mention alternatives or exclusions, such as 'for a single task use get_task' or 'for broader search use search'. The guidance is implied but not 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?

With no annotations provided, the description fully carries the burden of behavioral disclosure. It clearly states the destructive effect (removing the API key from OS keychain and local file) and the follow-up behavior (next tool call will re-prompt for setup). This is transparent for a logout operation, though it could mention whether the remote session is invalidated.

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

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

The description is two sentences with no filler. The primary action is stated first, followed by the consequence, making it easy to scan and understand.

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, destructive logout tool with no output schema, the description covers the essential information: what is removed, where it is removed, and what happens next. No critical detail is missing for an agent to call it correctly.

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

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

The tool has zero parameters, so the schema provides complete coverage by definition. The description adds useful context about the side effects, satisfying the baseline for parameterless tools.

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 ('Remove') with a clear resource ('stored Teamwork API key') and states the scope ('from this machine (OS keychain + local file)'). This clearly distinguishes it from siblings like auth_status and whoami, which inspect rather than clear authentication state.

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 conveys when to use the tool: when the user wants to remove the stored API key and re-authenticate, as indicated by 'The next tool call will ask to set up again.' However, it does not explicitly contrast this with auth_status or other related tools, nor does it state when not to use 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 fails to mention that at least one of taskId or projectId is required (a critical constraint visible only in the schema), whether the operation is reversible/editable, or the authentication/permission context. For a mutation tool that creates records, this is a significant transparency gap.

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

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

A single, efficient sentence that states the verb, resource, and scope with zero waste. The core purpose is front-loaded and immediately understandable.

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 mutation tool with 6 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain the critical requirement of providing taskId or projectId (only visible in the schema description for projectId), doesn't describe what the tool returns, and doesn't clarify the relationship between the two target types. With 6 parameters, an agent needs substantially more context to call this 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?

The input schema covers parameter descriptions at 83% coverage (all parameters are described except isBillable which only has type boolean). The description itself adds minimal parameter context—it doesn't clarify the taskId/projectId relationship or the default date behavior beyond what the schema's 'default today' already states. The description adds some value by noting both task and project targets, but doesn't fully compensate for the missing isBillable semantics.

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

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

The description clearly identifies the action (log a time entry) and the target resources (task or project), which accurately distinguishes it from typical project-management tools. However, it doesn't explicitly differentiate from sibling tools like task management or project creation tools, though the timesheet specificity provides reasonable clarity.

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 stating the core function but provides no explicit guidance on when to use this tool versus alternatives. It doesn't mention that taskId or projectId is required, nor does it address scenarios like logging time against both a task and project, or time-logging best practices. There's no exclusions or alternative tool routing.

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 readOnlyHint annotation already declares the tool is safe to call. The description adds value by clarifying the scope (tasks assigned to the API key's user) and the filtering behavior (due today, overdue, this week). It does not disclose pagination or response structure, but for a read-only list tool with annotations covering the safety profile, the added context is sufficient.

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 with no filler. It front-loads the primary resource ('tasks assigned to the API key's user') and then specifies the relevant time filters. Every word contributes to the purpose, making it efficiently scannable for an agent.

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

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

For a simple list tool with no output schema, the description covers the essential purpose and the main filtering dimensions. It does not explain the distinction between 'thisweek' and 'within7' or how pagination works, but these are partially inferable from parameter names and the schema enum. The tool is simple enough that the description, combined with annotations, provides adequate context for correct invocation.

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

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

Schema description coverage is low (only filter has a description), but the tool description partially compensates by enumerating due-date categories that map to filter enum values. However, page, pageSize, and includeCompleted are not explained in the description, leaving their semantics to the schema (which lacks descriptions). The description adds some meaning for filter but not for the other three parameters, so it does not fully bridge the gap.

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 identifies the tool's purpose: listing tasks assigned to the API key's user, with explicit mention of due-date categories (today, overdue, this week). This distinguishes it from general task lists like list_tasks, though it does not explicitly name an alternative. The verb 'assigned' and resource 'tasks' are specific, 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 when to use this tool (when you need tasks for the current user with due-date filtering) but provides no explicit guidance on when not to use it or which alternative to choose. It does not mention list_tasks or get_task, and it does not clarify scenarios like 'use this for personal task overview' vs 'use list_tasks for all tasks'. This is a gap for an agent deciding between siblings.

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 readOnlyHint annotation already covers safety, and the description adds that the data are 'latest' health reports posted on projects. It does not mention pagination behavior, the activeOnly default, or response characteristics, but it does not contradict annotations.

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

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

The description is a single, front-loaded sentence with no filler. It is concise, though it borders on under-specification rather than being genuinely informative.

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 list tool with four optional parameters, no output schema, and no usage guidance, this description is too thin. It leaves pagination defaults, return field structure, and filter interactions to be inferred from the schema alone.

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 only 25% schema description coverage, the description needed to compensate for the undocumented page, pageSize, and projectIds parameters, but it provides no parameter-level detail at all. It does not even clarify that projectIds filters to specific projects.

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 identifies the resource as 'status updates (health reports)' and scopes them to projects, so an agent can tell what the tool returns. However, it does not explicitly distinguish this from sibling tools like latest_activity or list_projects, so it falls 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?

There is no guidance on when to use this tool versus siblings such as latest_activity, list_projects, or upcoming_milestones. The description conveys no selection criteria, prerequisites, or exclusions.

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

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

The annotation readOnlyHint=true already signals a safe read operation. The description adds minimal behavioral context beyond purpose—it does not describe pagination, result format, or any side effects. Since the annotation covers the safety profile and the description doesn't contradict it, a score of 3 reflects the limited added value.

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

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

The description is a single, front-loaded sentence with no filler. It directly states the action and scope, making it efficient and easy to parse. 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 search tool with comprehensive schema descriptions and a read-only annotation, the description covers the core purpose adequately. It does not explain the response structure (no output schema), but the tool's nature and the parameter descriptions (limit, includeDetails) give enough context for an agent to invoke it. Minor gap: no mention of result ordering or default behavior, but these are inferable.

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 detailed descriptions for all parameters (e.g., 'Limit result types', 'Only this project', 'Keyword to search for'). The description only restates the search keyword concept and lists content types that are already reflected in the 'types' parameter. It does not add meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a clear action ('Search') with a specific resource (tasks, messages, files, comments, milestones, notebooks, links) and scope ('across the site'). It distinguishes itself from sibling tools like list_tasks or get_task by covering multiple content types globally, so an agent can easily tell when to use this tool.

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 global search but does not explicitly state when to use it versus alternatives, nor does it mention exclusions (e.g., 'use list_tasks for a specific project without search'). The usage context is inferred rather than stated, which is adequate but not 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=true, so the description does not need to repeat safety behavior. It adds useful context by stating that results span projects and default to the next 30 days, but it does not disclose important behaviors such as whether completed milestones are included by default, sorting, or pagination 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?

The description is two short sentences with no filler. The core purpose is front-loaded in the first sentence, and the default behavior is stated in the second, making it efficient and easy to scan.

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 five optional parameters, no output schema, and only 40% schema coverage, this description is too lean. It explains the core purpose and default date range but omits parameter semantics, filtering behavior, and return expectations, leaving an agent with meaningful gaps when deciding how to invoke it correctly.

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

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

Schema description coverage is only 40%, so the description carries significant responsibility for explaining parameters. It adds meaning for the date range and default window, but it does not clarify projectIds, includeCompleted, or pageSize, leaving three parameters effectively undocumented and reducing the tool's usability.

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 identifies the resource as milestones with deadlines over a date range across projects, which is specific and understandable. However, it uses a noun phrase rather than an explicit verb like 'list' or 'retrieve,' and it does not explicitly differentiate itself from sibling tools such as list_tasks or search.

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 mentions a default date range but provides no guidance on when to prefer this tool over alternatives like list_tasks, my_work, or search. No exclusions, prerequisites, or alternative tool references are given, so an agent must infer appropriate usage from the name and schema 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 full responsibility. It states the operation is an update but does not disclose side effects such as whether unspecified fields are preserved, that tagIds and assigneeUserIds replace existing ones, or what the response contains. This is insufficient for a mutation tool.

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

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

A single, well-structured sentence that front-loads the primary purpose and mentions a key option. No wasted words.

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

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

For a simple update tool with 8 parameters, the description is adequate but omits important behavioral context like replacement semantics and return values. It does not fully compensate for the absence of annotations.

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 75%, so most parameters already have clear meanings. The description adds no extra parameter details beyond what the schema provides, e.g., it does not emphasize replacement semantics for arrays.

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 ('Update fields of an existing task') and the resource (task), plus a specific use case (mark complete with complete=true). It naturally distinguishes from siblings like create_task or get_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?

It implies usage for existing tasks and highlights a special case (completion), but does not explicitly mention when not to use it or name alternatives. Given the context, the intended use is obvious.

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 readOnlyHint annotation already signals no side effects, but the description adds meaningful context by specifying the exact output (user, site URL, admin status) and tying it to the API key owner. This goes beyond the annotation without contradicting it, providing the agent with concrete expectations about the response.

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 action and then lists the three key pieces of information returned. There is no redundancy or filler, and it is immediately scannable.

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

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

For a simple no-parameter, read-only tool without an output schema, the description provides sufficient information: it names the resource and the specific fields returned. It does not mention error cases or authentication prerequisites, but these are implied by 'configured API key'. The tool is complete enough for an agent to know what to expect.

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?

There are zero parameters, so the schema coverage is trivially 100%. The baseline for 0 params is 4, and the description does not need to explain any parameters. It correctly focuses on output rather than input, which is appropriate for a no-arg tool.

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 ('Return'), a precise resource ('the Teamwork.com user that owns the configured API key'), and enumerates the returned fields (user, site URL, admin flag). This clearly distinguishes it from sibling tools like auth_status (which likely only checks authentication) and list_people (which lists others). The purpose is unambiguous and self-contained.

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

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

No explicit guidance is given on when to use this tool versus alternatives. It does not mention that this is the tool for retrieving current-user details, nor does it contrast with auth_status or logout. The description only states what it does, leaving the agent to infer when it is appropriate. This is a clear gap.

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