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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds only the 'Teamwork Chat conversation' scope, which is context but not new behavioral disclosure 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, focused sentence that front-loads the action and resource. Every word earns its place, with no redundant or vague phrasing.

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?

This is a simple get-by-ID tool with one parameter, full schema coverage, and clear annotations. The description is sufficient for an agent to understand what the tool does and how to invoke it correctly, given the low complexity and strong structured metadata.

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% and the parameter description already explains conversation_id as 'The ID of the conversation to retrieve.' The tool description's 'by ID' adds no additional meaning beyond the schema, matching the baseline 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 clearly states the verb 'Get' and the resource 'Teamwork Chat conversation' with a specific scope ('single', 'by ID'). This distinguishes it from sibling tools like twchat-list_conversations, making its purpose unambiguous.

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

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

The phrase 'single ... by ID' clearly implies when to use this tool (when you have a known conversation ID) and differentiates from listing all conversations. However, it does not explicitly name alternative tools or provide exclusions, so it stops short of a 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?

The annotations already declare readOnlyHint=true and destructiveHint=false, so the description need not restate safety. It adds value by specifying the output categories (identity, unread counts/mentions, settings), which gives the agent a better sense of what to expect.

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, front-loaded sentence with no wasted words. It puts the verb and resource first, then enumerates the key output categories in a compact list.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so by listing identity, counts, and settings. It could have mentioned pagination or exact formatting, but for a simple read-only profile endpoint, the information is sufficient.

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

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

The tool has zero parameters and the schema is empty (100% covered), so there are no parameter semantics to explain. The description correctly focuses on the return payload, which is the only thing the agent needs to understand for invocation.

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 names the exact resource ('current authenticated Teamwork Chat user'), and it lists returned content (identity, counts, settings). This distinguishes it from sibling chat tools like list_conversations, list_messages, and list_people, 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 phrase 'current authenticated' implies the tool is for accessing the caller's own chat profile, which provides clear context for when to use it. However, it does not explicitly name alternatives or state when not to use it, so it falls slightly short of a 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?

Beyond the annotations, the description discloses the creation side effect, the returned conversation's downstream use, and the self-target rejection edge case. These are meaningful behavioral details that help an agent predict outcomes and avoid errors.

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

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

The description is compact and front-loaded with the core behavior, followed by return usage, parameter lookup, and the key exclusion. Every sentence is informative with no 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 single-parameter tool with no output schema, the description covers purpose, side effects, return value usage, parameter sourcing, and a critical rejection case. The agent has enough information to call the tool successfully.

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

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

The schema already documents user_id and its constraint at 100% coverage, so the baseline is 3. The description adds extra value by telling the agent how to resolve the parameter via list_people and explicitly warning that the authenticated user's own id is rejected.

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: get or create a 1:1 direct-message conversation with a person. It distinguishes itself from siblings like send_message and get_conversation by emphasizing both the retrieval and creation 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?

It gives clear contextual guidance by telling the agent to use list_people to find user_id and to use the returned conversation id with send_message. It does not explicitly name when to prefer this over twchat-get_conversation, but the create-if-missing semantics make the choice reasonably clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the membership constraint (only conversations the current user belongs to), which is useful behavioral context. It does not disclose pagination limits (page_limit max 10), default sort, or return shape, but with annotations carrying the safety burden, this level is adequate.

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 12-word sentence with zero waste. The verb and resource are front-loaded, and the scope qualifier packs meaningful discrimination into the shortest possible form.

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

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

For a read-only list operation with 100% schema coverage and safety annotations, the description covers the essential purpose and scope. The only gaps are unpaginated return-shape details (no output schema exists) and the lack of sibling routing, neither of which is critical for a straightforward list 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%, and all 7 parameters (sort, type, status, page_limit, page_offset, search_term, include_message_data) have descriptive schema text including full enum values. The description adds no parameter-level meaning, which is fine because the schema fully documents them — baseline 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 ('List') and a specific resource ('Teamwork Chat conversations') with a clear scope qualifier ('the current user is a member of'). This scope distinguishes it from sibling tools like twchat-get_conversation (single conversation) and twchat-list_messages (messages within a conversation), so an agent can identify it without opening 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 membership scope implies the usage context — this tool returns the current user's own conversations rather than all conversations in the workspace. However, it provides no explicit guidance about when to prefer it over siblings like twchat-get_conversation or twchat-list_messages, nor any exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read-only nature is covered. The description adds no behavioral detail beyond the listing action, such as pagination behavior, default ordering, or how cursor parameters affect results. It does not contradict 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 a single concise sentence that front-loads the core purpose and the essential requirement. There is no filler or 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?

The schema and annotations cover parameters and safety, but the description lacks guidance on when to choose this tool over similar list tools, how pagination works, or what the returned message objects contain. It is functional for invocation with the required ID but leaves several contextual gaps.

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

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

Schema description coverage is 100%, and all parameters are individually documented, including detailed examples for created_after and created_before. The description only reiterates that conversation_id is required, which the schema already states, so it adds minimal semantic value beyond the schema.

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

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

The description uses a specific verb and resource: 'List messages within a Teamwork Chat conversation.' It clearly identifies the tool's scope and the required conversation_id, distinguishing it from conversation-level tools like twchat-get_conversation and twchat-list_conversations.

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 tool is for listing messages when you already have a conversation_id, but it does not explicitly state when to use this tool versus alternatives, nor does it mention how to obtain a conversation_id using a sibling tool. Usage context is present but not fully developed.

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 this as a safe read operation (readOnlyHint=true, destructiveHint=false). The description adds the scope of the operation ('Teamwork Chat installation') but does not describe pagination behavior, whether inactive people are included, or result sizing, so additional behavioral context is limited.

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

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

Two short sentences with no filler. The action is front-loaded and the second sentence justifies the tool's purpose without repeating the schema or annotations.

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

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

For a simple read-only list tool with three optional parameters and no output schema, the description is nearly complete: it explains what is listed, where, and why. It could mention that the result is a list of person objects with IDs, but the given use case already implies the relevant output.

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

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

Schema description coverage is 100%, so the parameters are already fully documented in the input schema. The description's use case hints at search_term for name/email lookup but adds no parameter-level information beyond the schema, matching the baseline 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 action and resource: listing people in the Teamwork Chat installation, and adds a concrete use case (resolving names to user IDs). It is distinguishable from sibling tools like twchat-get_current_user and user-list tools in other domains, 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?

The phrase 'Useful for resolving names to user IDs' gives a clear reason to choose this tool when an agent needs to map names to IDs. It does not provide explicit when-not-to-use guidance or name alternatives, so it misses the top score.

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

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

The description adds meaningful behavioral details beyond the annotations: it auto-creates/resolves the conversation and explicitly says a self-recipient request is rejected with nothing sent. Since annotations already signal non-readonly and non-idempotent behavior, the extra context covers the most important operational nuance.

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 tightly packed sentences cover the action, required parameters, lookup hint, and a critical failure case without wasted words. The most important operational detail (auto-resolving the conversation) is front-loaded.

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

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

Given the tool's simplicity, complete schema, and existing annotations, the description covers the key operational behavior and edge case. It does not describe the success return value, but the absence of an output schema is partly mitigated by the straightforward send action.

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% and both parameters are well documented in the schema. The description adds a cross-tool discovery hint ('Use list_people to find user_id') but otherwise mostly restates the required parameters, so it does not substantially elevate meaning beyond the schema.

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

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

The description states a specific action ('Send a direct message to a person') and a distinct behavioral feature ('resolving (or creating) the 1:1 conversation automatically'). This clearly differentiates it from sibling tools like twchat-send_message by focusing on person-to-person DM and automatic conversation resolution.

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

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

The description gives useful guidance such as 'Use list_people to find user_id' and explains the self-recipient rejection case. However, it does not explicitly compare this tool to alternatives like twchat-send_message or state when one should be preferred over the other, so the usage context is implied rather than fully 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 indicate a write operation (readOnlyHint=false), and the description adds that it requires mandatory parameters and performs a send action. However, it does not disclose any behavioral details such as potential failures, rate limits, or side effects. The description adds minimal context beyond the annotations, so a 3 is appropriate.

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 efficiently states the tool's purpose and required parameters. Every word earns its place, with 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?

Given the tool's simplicity (two well-documented parameters, no output schema, minimal annotations), the description covers the core action and inputs. However, it lacks explicit differentiation from the DM tool and fails to mention any post-send behavior or error conditions, which leaves it slightly incomplete for a fully contextual understanding.

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 full descriptions for both parameters (conversation_id as integer, body as Markdown string). The description only restates that they are required, adding no semantic value beyond the schema. With 100% schema coverage, the 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 clearly states the action ('Send a message') and the target resource ('Teamwork Chat conversation'), and it explicitly mentions the required parameters. However, it does not explicitly distinguish this tool from the sibling `twchat-send_dm`, so it gets a 4 instead of 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 provides no guidance on when to use this tool versus alternatives such as `twchat-send_dm` or when not to use it. There is no explicit context or exclusion, so the agent receives no usage guidance.

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

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

The description adds no behavioral disclosure beyond the annotations; it simply repeats the creation action. It does not mention auth requirements, duplicate handling, side effects, or return behavior. The annotations already indicate a non-read-only, non-destructive, non-idempotent operation, so there is no contradiction, but the description itself provides little transparency 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 very short and contains no redundant wording. However, it is so minimal that it approaches under-specification rather than being an appropriately sized definition; there is no contextual structure or detail beyond the single creation statement.

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 input schema is rich and fully documented, and the annotations clarify the basic safety profile, so the description plus schema is minimally sufficient for a basic creation call. However, there is no output schema, no mention of expected return values, and no usage differentiation from the large set of sibling tools, leaving meaningful gaps.

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

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

Schema description coverage is 100%, and the schema adequately documents all parameters including enums and required fields. The tool description contributes no parameter-level semantics, so the baseline of 3 applies because the schema carries the full burden.

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 the action clearly: create a Desk company. The word 'Desk' distinguishes it from twprojects-create_company, and the verb 'create' separates it from twdesk-update_company. It is terse and does not explain what a company represents, but the core purpose is clear.

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

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

No guidance is provided about when to use this tool versus alternatives. The description does not mention that it is for new companies, that twdesk-update_company is for existing companies, or that twprojects-create_company is a different product. An agent must infer usage entirely from the tool name.

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 indicate this is a mutating, non-idempotent operation, and the description merely says 'Create customer,' adding no behavioral context beyond that. It does not mention what happens on duplicate data, whether any fields are effectively required, or what response to expect.

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 very short and contains no verbose filler, but it is under-specified rather than efficiently informative. A single sentence that essentially restates the tool name does not earn high marks for structure, though it is at least clear and direct.

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 operation with 13 optional-looking parameters and no output schema, the description provides almost no context an agent needs to call it correctly. It does not explain which fields should be supplied, whether a name or email is expected, or what a successful creation returns.

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?

All 13 parameters have schema descriptions such as 'The email of the customer' and 'The phone number of the customer,' so the schema already provides full parameter coverage. The tool description adds no parameter-specific meaning, which keeps this at the baseline for high 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 states a clear verb and resource: 'Create customer.' This unambiguously identifies the operation as creating a customer record. It does not, however, add any distinguishing detail beyond the tool name itself, such as what a customer is or which sibling it differs from.

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

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

The description gives no guidance on when to use this tool versus alternatives like twdesk-update_customer, twdesk-get_customer, twdesk-list_customers, or twdesk-create_company. There is no mention of prerequisites, context, or cases where another tool should be preferred.

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 indicate a non-read, non-idempotent, non-destructive operation; the description adds that the tool returns an ID and that the file is intended for attachment to tickets or messages. It does not surface additional constraints like upload size limits or authentication requirements, but the annotations lower the bar.

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

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

Two short sentences, front-loaded with the core action and immediately followed by the key downstream purpose. 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 simple upload tool with a full input schema and no output schema, the description covers the essential missing piece: the call returns an ID to use for attachment. It is slightly terse about the exact response shape, but enough for an agent to invoke and use the result.

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 are already documented with meaningful descriptions. The tool description adds no parameter-specific detail beyond that coverage, so it stays at the baseline.

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 the specific action 'Upload file' and the resource type, then adds the desk-specific purpose ('Attach the returned ID to tickets or messages'). This distinguishes it from sibling twprojects-create_file and other project-upload tools even without naming 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 phrase 'Attach the returned ID to tickets or messages' gives clear context for when this tool is appropriate. It does not explicitly list exclusions or alternative upload tools, so it falls short of full routing guidance.

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

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

The description repeats the create action already implied by the name and annotations (readOnlyHint=false, idempotentHint=false). It does not disclose any additional behavioral traits such as required permissions, uniqueness constraints, side effects, or rate limits. It does not contradict 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 a single sentence with no fluff and front-loads the action. However, it is so minimal that it essentially restates the tool name, only adding the word 'new'.

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 operation with 6 parameters and no output schema, the description provides no information about return values, required workflow, or expected result. The only meaningful context comes from the schema and annotations, which is inadequate for an agent to fully understand invocation 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 documents all 6 parameters with descriptions, giving 100% schema coverage, so the baseline is 3 despite the tool description adding no parameter-level meaning. The siteID parameter description provides extra discovery guidance, but that is schema content rather than tool description content.

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

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

The description states a specific action and object: 'Create a new help doc article.' It clearly differentiates from sibling tools like twdesk-update_helpdoc_article or twdesk-get_helpdoc_article via the verb 'create'. However, it adds no specifics about what article creation entails or any scope, stopping 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 gives no guidance on when to choose this tool over alternatives such as twdesk-update_helpdoc_article or twdesk-search_helpdoc_articles. There is no mention of prerequisites, exclusions, or typical use cases. The only usage pointer ('Use twdesk-list_helpdoc_sites to discover.') lives in the siteID parameter schema, not in the tool description.

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 indicate a write operation (readOnlyHint=false) and that the tool is not destructive or idempotent. The description is consistent with those annotations but adds no extra behavioral context such as uniqueness constraints, side effects, or required permissions.

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 short sentence with no filler or redundancy. It is appropriately compact for a simple create tool with two parameters, though it is terse enough that it relies heavily on the schema and tool name.

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 create operation with one required and one optional parameter, the description plus schema is nearly sufficient. However, there is no output schema, and the description does not clarify return behavior or the expected format for 'color', leaving minor gaps for the agent to resolve.

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 itself adds no parameter-level meaning; the schema already describes 'name' and 'color', though 'color' lacks an expected format or example.

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 ('Create') and a specific resource ('ticket priority'), which distinguishes it from read-only and update siblings like twdesk-get_priority, twdesk-list_priorities, and twdesk-update_priority. It is clear but lacks any additional context about what a ticket priority is, 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?

The imperative phrasing implies this tool is for creating a new ticket priority, and the sibling tool names naturally suggest alternatives for reading or updating priorities. However, there is no explicit when-to-use guidance, no exclusions, and no mention of prerequisites or related tools to prefer.

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

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

The description adds little beyond the annotations: it repeats the creation action and adds the 'ticket' domain qualifier. It does not disclose whether duplicate names are rejected, whether color or displayOrder have defaults, or what the API returns after creation.

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 economical sentence with no filler and the key action/resource are front-loaded. It is under-specified in behavioral terms, but this is a conciseness issue rather than verbosity.

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

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

For a simple create operation with fully documented parameters, this is minimally adequate. However, with no output schema, the description does not clarify return behavior, side effects, or uniqueness constraints, leaving moderate gaps for an agent selecting or invoking the 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 input schema already documents name, color, and displayOrder completely. The description adds no parameter-level meaning, but the schema fully carries that burden, so 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 states a clear verb ('create') and resource ('ticket status'), which is specific enough to distinguish from sibling tools like twdesk-create_priority or twdesk-create_ticket_type. It does not explicitly contrast with update_status or list_statuses, but the core 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 is provided on when to use this tool versus alternatives such as twdesk-update_status for modifying statuses or twdesk-list_statuses for viewing existing ones. An agent must infer usage entirely from the tool name and sibling list.

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 simply restates that a tag is created, which is already implied by readOnlyHint=false. It adds no context about uniqueness constraints, required permissions, idempotency, or effects on existing tickets. There is no contradiction with annotations, but no additional behavioral disclosure either.

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

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

The description is extremely concise with zero wasted words, and the 'Desk' qualifier is useful for disambiguation. However, it is so skeletal that it provides little structural or orienting information beyond the tool name.

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 create operation with a fully documented 2-parameter schema and annotations, this is minimally workable. But with no output schema and no mention of behavior or return value, an agent gets little help beyond the bare operation and parameter 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 100%, and both parameters (name and color) already have clear descriptions in the input schema. The tool description adds no parameter-level context, so 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 operation ('Create') and resource ('Desk tag'), and the 'Desk' qualifier helps distinguish it from twprojects-create_tag and twspaces-create_tags. However, it mostly mirrors the tool name without adding domain context about what a Desk tag is used for.

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 create a new tag versus reuse an existing one, nor any reference to sibling tools like twdesk-create_status or twdesk-create_priority. The usage context is only implied by the verb 'Create'.

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

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

The description adds no behavioral disclosure beyond the annotations, which already mark this as non-read-only and destructive. It does not mention side effects such as customer auto-creation or customer notification, though these are partially documented in the schema. No contradiction exists, but no extra context is provided.

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

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

The description is extremely short and readable, but it is under-specified rather than appropriately concise. Despite the tool having 14 parameters and a destructive annotation, the entire description is only two words and provides no context, usage, or side-effect 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?

Given 14 parameters, a destructive/open-world annotation, and no output schema, a two-word description leaves significant context unexplained, such as when creating a ticket is appropriate and what side effects may occur. The rich schema partially compensates, but the description alone is not enough for an agent to invoke the tool 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?

All 14 parameters have schema descriptions, including cross-tool references such as twdesk-list_tags and twdesk-list_inboxes, as well as the conditional rule for customerEmail versus customerId. The description itself contributes no parameter semantics, but because schema description coverage is 100%, the 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 'Create ticket.' is a direct restatement of the tool name and the annotated title 'Create Ticket', adding no further scope. It identifies the verb and resource but does not distinguish this create action from related ticket operations such as twdesk-update_ticket or twdesk-reply_ticket beyond the verb already present in the name.

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 about when to choose this tool over related ticket operations; it does not mention update_ticket, reply_ticket, or any prerequisite like needing an inbox. The only context is implied by the word 'Create', which is insufficient for an agent deciding among the ticket-related 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 description only says 'Create ticket type' and adds no behavioral context beyond what the annotations already imply. It does not mention side effects, required permissions, uniqueness constraints, or how the created ticket type interacts with other resources. It is consistent with the annotations, so there is no contradiction, but it provides no additional 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, front-loaded sentence with no wasted words. It is appropriately terse for such a simple create operation, though it is so minimal that it provides little value beyond the tool name and title.

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 create operation with 3 parameters and full schema coverage, the description is minimally viable. However, it lacks usage guidance, behavioral notes, and any indication of what a successful creation returns or affects, so an agent gets just enough to proceed but not enough to be fully confident.

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

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

Schema description coverage is 100%, so the parameters are already well documented in the input schema. The description itself does not add any parameter-level meaning, which matches the baseline expectation when the schema carries the full burden.

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 operation (create) and the resource (ticket type), so an agent can tell this creates a new ticket type rather than merely reading one. However, it does not distinguish itself from sibling tools like twdesk-update_ticket_type or twdesk-get_ticket_type beyond the verb, and it closely mirrors the title.

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

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

The description gives no guidance on when to use this tool versus alternatives such as twdesk-update_ticket_type, twdesk-list_ticket_types, or twdesk-get_ticket_type. There is no mention of prerequisites, context, or exclusions, leaving the agent to infer appropriate usage 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond 'Get', but it does not contradict 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?

A single sentence that front-loads the action and resource, with the parenthetical earning its place by disambiguating company from customer. There is no wasted wording.

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

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

For a simple read-by-id tool, the required id and optional fields are fully documented in the schema and annotations confirm read-only behavior. It does not explicitly state return shape or not-found behavior, but the get semantics and schema make the primary invocation case well-covered.

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

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

Schema description coverage is 100%: both id and fields are documented, including the sparse fieldset behavior. The description itself adds no parameter-specific meaning, so the baseline of 3 is appropriate.

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

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

States a specific verb (Get), resource (Desk company), and a clarifying parenthetical (customer organization). This helps distinguish it from sibling tools like twdesk-get_customer and twprojects-get_company despite the similar get_* naming.

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

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

No guidance is provided on when to use this tool versus twdesk-list_companies or twdesk-get_customer. The only usage signal is the implicit 'Get' plus the required id parameter, which is not sufficient guidance for an agent choosing among many 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?

The description contributes no behavioral detail beyond the annotations: readOnlyHint=true and destructiveHint=false already establish it as a safe read. It does not mention not-found behavior, response shape, authentication needs, or sparse-field semantics. There is no contradiction with the annotations, but the description adds nothing.

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 words are under-specification rather than useful conciseness; the sentence 'Get customer.' repeats the name/title and earns no space in the definition. There is no front-loaded context or structure that helps 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?

The definition lacks an output schema and the description does not describe the returned customer object, failure cases, or how this fetch relates to list_customers. Annotations and schema cover parameter and safety basics, but the overall definition is too spare for confident invocation in a toolset with hundreds of siblings.

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

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

The input schema has 100% description coverage: id and fields are fully documented, including the sparse-fieldset meaning of fields. The description adds nothing about parameters, but per the baseline for high schema coverage, 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?

Description 'Get customer.' is a verbatim restatement of the tool name and title, so it provides no additional clarifying information. It names the resource but does not distinguish single-record retrieval from twdesk-list_customers or other twdesk-get_* lookups. This is tautological rather than informative.

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

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

The description gives no when-to-use guidance, prerequisites, or alternatives. Among the many siblings, twdesk-list_customers exists for finding customers and twdesk-get_company/get_user fetch related entities, but an agent cannot infer from the description which one to select. No exclusions or context cues are provided.

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 destructiveHint=false, so the description does not need to repeat safety behavior. It adds no extra behavioral context (e.g., 404 behavior, auth, or sparse-field effects), but there is no contradiction and the read-only nature is clear.

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 clear sentence states the operation, resource, and required input with no filler. The key scoping information ('by ID') is front-loaded.

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

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

For a simple two-parameter getter with read-only annotations and no output schema, the description plus schema is sufficient to call the tool correctly. A small gap is the lack of any mention of what the response contains, but this is largely inferable for a 'get' 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 id and fields are already fully documented. The description adds no additional parameter meaning, which is acceptable given that the schema carries the burden.

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'), names the exact resource ('help doc article'), and states the retrieval criterion ('by ID'). This clearly distinguishes it from sibling tools like twdesk-search_helpdoc_articles and twdesk-get_helpdoc_site.

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?

'by ID' implies this tool is appropriate when the caller already has a help doc article ID, but there is no explicit guidance about when to prefer it over search_helpdoc_articles or how to obtain an ID. 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?

Annotations already establish that this is a safe read-only operation (readOnlyHint=true, destructiveHint=false). The description adds some context by identifying the resource as a knowledge base and noting the returned fields, but it does not disclose additional behavioral traits like authorization requirements or response limitations. No contradiction with annotations found.

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 compact sentence that front-loads the action and resource, then adds the most useful response details. Every part earns its place with no redundant or vague 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 simple single-get tool with complete schema coverage and read-only annotations, this description is largely sufficient. It names key return fields despite no output schema. It could be slightly more complete by pointing to list_helpdoc_sites for ID discovery, but that is not essential for correct invocation.

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

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

Schema description coverage is 100%, so the baseline applies. The id parameter is adequately documented in the schema, and the fields parameter is already well explained as a sparse fieldset. The description adds no new parameter-level meaning beyond restating that retrieval is by ID.

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

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

The description clearly states the operation: 'Get a help doc site (knowledge base) by ID' and names what the response includes ('subdomain, branding and article counts'). This differentiates the tool from sibling getters like get_helpdoc_article and listing/search tools by both resource type and lookup method.

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

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

The usage is implied: use this when you have a help doc site ID and need its details. However, it does not explicitly mention alternatives such as twdesk-list_helpdoc_sites for discovery when the ID is unknown, nor does it 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?

The description adds no behavioral context beyond the annotations, which already declare readOnlyHint=true and destructiveHint=false. There is no mention of return shape, sparse fieldset behavior, or any side effects, leaving the annotations to carry all the weight.

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

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

The description is extremely concise at three words, with no fluff. However, it is under-specified and does little more than echo the title, so it is not a well-earned sentence despite its brevity.

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

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

For a simple read-only getter with a clear schema and annotations, the bare description is arguably workable. Still, it lacks any note about the required ID, the distinction from list_inboxes, or the response contents, leaving minor gaps 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?

Schema description coverage is 100%, with id and fields both clearly documented. The description itself says nothing about parameters, so it does not add value beyond the schema; 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 'Get inbox.' clearly states the verb and resource, making the core operation obvious. However, it merely restates the tool name and title and does not differentiate from sibling tools like twdesk-list_inboxes or other get_* tools, so it misses the top tier.

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 usage guidance is provided. The description gives no indication of when to use this tool versus alternatives, nor does it mention that an inbox ID is required. An agent must infer usage entirely from the schema and naming conventions.

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 destructiveHint=false, covering the safety profile. The description adds no behavioral context beyond the annotations — no mention of not-found behavior, return shape, or error handling — but it also does not contradict them, so a mid-score is appropriate.

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 five-word sentence with zero filler, and the core purpose is front-loaded. The brevity is efficient but borders on under-specification rather than deliberate compression, since usage and behavioral guidance are entirely absent.

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 get-by-id tool with two fully documented parameters and safety annotations, the definition is minimally adequate. Gaps remain: no guidance distinguishing it from list_priorities, no description of what is returned (no output schema exists), and no indication of behavior for invalid IDs.

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%: the schema fully documents `id` ('The ID of the priority to retrieve') and `fields` ('Sparse fieldset... Omit to receive all fields'). The description adds no parameter-level meaning, but with full schema coverage, the 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 states a specific verb ('Get') and resource ('ticket priority'), making the purpose unambiguous as a single-entity retrieval operation. It is clear but does not differentiate itself from the many sibling get_* tools (e.g., twdesk-get_status, twdesk-get_ticket_type) beyond the resource name, which is already evident from the tool name.

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 about when to use this tool versus alternatives such as twdesk-list_priorities, twdesk-get_ticket, or the other get_* siblings. No context is provided about needing a known priority id or when a sparse fieldset would be appropriate, leaving selection entirely to inference.

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

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

The description adds no behavioral detail beyond the word 'Get.' Annotations already indicate readOnlyHint=true and destructiveHint=false, but the description contributes no additional context such as authentication requirements, response shape, pagination, or idempotency implications. No contradiction exists, but the description does not enrich 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 a single sentence with no wasted words, which is concise. However, it is under-specified: it omits any context about when to use it, how it relates to sibling tools, or what output to expect. It is not tautological, but it is minimal rather than appropriately structured.

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 get-by-id tool, the schema covers the parameters and annotations cover the safety profile. Yet the description fails to disambiguate from list_statuses or get_ticket, and with no output schema it would benefit from at least noting that it returns a single status object. It is adequate for a trivial call but not fully complete.

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

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

Schema description coverage is 100%, with id described as 'The ID of the status to retrieve' and fields as a sparse fieldset. The description itself adds no parameter-level meaning, but the schema fully carries that burden, so a 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?

Description states a specific verb and resource: 'Get ticket status.' It clearly names the domain (ticket) and the object (status), and distinguishes from list_statuses by implying a single resource. However, it does not explicitly differentiate from get_ticket, which could also return status information, so it is clear but lacks sibling differentiation.

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

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

No guidance is provided on when to use this tool versus alternatives such as twdesk-list_statuses or twdesk-get_ticket. There are no conditions, exclusions, or references to sibling tools, leaving the agent to infer 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe-read nature is covered by structured metadata. The description adds no further behavioral context, such as sparse fields behavior or error semantics, but it does not contradict the annotations either.

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 words, no filler, and the core operation is front-loaded. For a simple get-by-ID tool, this is appropriately sized and does not waste an agent's attention.

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 and annotations make the tool callable, but the description provides no return-shape information despite the absence of an output schema, and it does not mention how this relates to list or update tag operations. It is adequate but sparse for a complete picture.

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%, with both id and fields clearly documented in the input schema. The description itself adds no parameter-level detail, but the baseline of 3 is appropriate because the schema carries the informational load.

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 'Get Desk tag' uses a clear verb and resource, and the 'Desk' qualifier helps distinguish it from sibling tag-getters in other domains. However, it does not explain what a Desk tag is or explicitly state that this retrieves a single tag by ID, so it falls short of a fully differentiated 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 about when to use this tool versus alternatives like twdesk-list_tags or even twprojects-get_tag. The required id parameter implies a single-object lookup, but the description itself provides no context for selection, exclusions, or alternative 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 and destructiveHint=false, but the description adds no behavioral context such as error behavior, authentication needs, idempotency, or return format. There is no contradiction with annotations, but the description contributes no additional 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 extremely short, but this is under-specification rather than effective conciseness. It contains no useful structure or front-loaded information beyond repeating the tool name.

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 retrieval tool with no output schema, the description leaves out important context such as what is returned, how to handle the optional fields parameter, and when to prefer this over twdesk-search_tickets. The schema helps with parameters, but the description alone is not complete enough for confident 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?

The input schema has 100% description coverage for both parameters: id and fields. The description itself adds no parameter semantics, but the schema already explains what each parameter does, so a 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, 'Get ticket.', is essentially identical to the tool name/title and adds no clarifying detail. It names the resource but does not differentiate this retrieval action from sibling tools like twdesk-search_tickets or twdesk-get_ticket_type.

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 about when to use this tool versus alternatives. The description does not mention that this retrieves a single ticket by ID, nor does it contrast with twdesk-search_tickets or other get_* tools, so the agent is left without selection criteria.

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=true and destructiveHint=false annotations already convey that this is a safe read operation, so the description is not required to restate that. However, the description adds no additional behavioral context such as error handling, permissions, or caveats; it is adequate but not informative beyond annotations.

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

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

The description is extremely short and has no filler, but it is under-specified rather than appropriately sized. A single tautological sentence does not earn full marks for structure because it leaves out scoping or sibling differentiation.

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 no output schema, the description should at least indicate that it returns a single ticket type and clarify when to use it rather than twdesk-list_ticket_types. The current description, combined with the schema, is minimally invocable but not complete enough for reliable tool selection.

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

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

Schema description coverage is 100%, and both parameters (id and fields) are already documented with meaningful descriptions. The tool description contributes no additional parameter nuance, 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 'Get ticket type.' simply restates the tool name twdesk-get_ticket_type and the annotation title 'Get Ticket Type', providing no new information about what the tool does. It names the resource but does not differentiate this from sibling tools like twdesk-list_ticket_types or twdesk-get_ticket.

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 alternatives such as twdesk-list_ticket_types or twdesk-search_tickets. An agent must infer from the name and schema that this fetches a single ticket type by ID; the description gives no selection criteria 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 annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond that—no return format, no behavior for nonexistent IDs, no auth expectations—so it contributes nothing extra beyond what the annotations and name already convey. There is no contradiction with the annotations, but also no added transparency 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 three words with zero wasted text, and the purpose is fully front-loaded. For a simple by-ID getter this is nearly the right size, though it borders on under-specification rather than demonstrating deliberate economy.

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

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

For a simple read-by-ID tool with a complete schema and safety annotations, this definition is mostly adequate. The notable gap is differentiation: with over 200 siblings including twprojects-get_user and twchat-get_current_user, the description should clarify which user pool this reads from, and there is no output schema to hint at the return shape.

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 of 3 applies: the schema fully documents both the required id parameter and the optional sparse-fieldset behavior of fields. The description's 'support agent' wording adds only minor role context, hinting that the id refers to a helpdesk agent, but it does not meaningfully compensate beyond the schema.

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

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

The description states a specific verb and resource: 'Get support agent.' The 'support agent' phrasing clarifies that this retrieves helpdesk user records, which distinguishes it from the sibling twprojects-get_user. However, it is terse and does not elaborate on what the resulting record contains, so it falls just 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 alternatives such as twprojects-get_user, twchat-get_current_user, or twdesk-list_users, and no exclusions are given. An agent must infer from the twdesk naming prefix that this tool belongs to the support-desk domain, which is an inference rather than explicit guidance.

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

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

Annotations are all false, so the description carries the burden. It discloses the effect on the ticket ('shows the work tracked') without delving into edge cases like idempotency or error handling, which is acceptable for a simple link operation. No contradictions with annotations.

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

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

The description is a single, concise sentence that leads with the action and object, and includes the purpose in a subordinate clause. Every word adds value, making it highly efficient for an agent to parse.

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

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

For a simple two-parameter link operation with no output schema, the description is complete. It explains the action, effect, and provides enough context for correct invocation, especially given the excellent parameter descriptions.

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% and each parameter description includes discovery hints ('Use twprojects-list_tasks or twprojects-search to discover' and 'Use twdesk-search_tickets to discover'). This goes beyond basic types, actively guiding the agent to obtain valid IDs, which is exceptional.

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 ('Link a Teamwork Projects task to a Desk ticket') with specific resources and a concrete outcome ('so the ticket shows the work tracked by that task'). It distinguishes itself from sibling inverse operation (twdesk-unlink_task_from_ticket) by focusing on the linking 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 'so the ticket shows the work tracked by that task' clause provides clear context on when this tool is appropriate: when the user wants to associate an existing task with a ticket. It doesn't explicitly mention exclusions or alternatives, 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 and destructiveHint=false, covering the safety profile. The description adds no further behavioral context such as pagination quirks, field selection, or return format, but it also does not contradict 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 short sentences with no filler. The action and resource are front-loaded, and the filter summary is immediately actionable.

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 rich input schema and read-only annotations, the description is largely sufficient for a straightforward list tool. The main gap is the lack of any routing guidance toward twdesk-get_company or clarification of the output shape, but this is not critical for invocation.

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

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

Schema description coverage is 100%, so the schema carries the parameter documentation burden. The description highlights name, domains, and kind as filters, but adds no extra meaning beyond what the input schema already provides.

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 operation ('List') and the resource ('Desk companies'), and names the main filter dimensions. This distinguishes it from related siblings like twdesk-get_company and twprojects-list_companies.

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

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

The usage is implied: use this tool to list or filter Desk companies. However, there is no explicit guidance about when to prefer twdesk-get_company for a single company, or how this tool relates to other list operations.

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 destructiveHint=false, covering the safety profile. The description adds no behavioral context beyond the schema, such as default result set size, pagination behavior, or that pageSize is silently capped at 100. With no extra disclosure, the description does not meaningfully enhance behavioral transparency 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?

Two short sentences with no filler. The core action 'List customers' is front-loaded, and the filter capability is stated immediately. Every word earns its place, and the description is appropriately sized for a straightforward read-only list tool.

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

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

For a tool with 8 fully documented parameters and read-only annotations, the description is minimally adequate but leaves some gaps. It does not mention that omitting all filters likely returns all customers, nor does it clarify return value structure (no output schema exists). An agent could call it correctly using the schema alone, but the description does not fully orient the agent to behavior like pagination or filtering combinations.

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

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

Schema description coverage is 100%, so the schema fully documents all 8 parameters. The description's 'Filter by company or email' restates the high-level function of the filter parameters but adds no new semantic meaning beyond what the schema already provides. Baseline of 3 is appropriate 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 states 'List customers', a specific verb and resource that distinguishes it from singular get_customer and from other list tools targeting different resources (companies, tags). However, it does not explicitly differentiate itself from sibling tools like twdesk-search_tickets or twdesk-list_companies, leaving some ambiguity for an agent choosing among related list/search tools.

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 alternatives. It mentions filtering by company or email, which implies a use case, but it does not state when to prefer this over twdesk-get_customer, twdesk-search_tickets, or other list tools, nor does it mention any exclusions or prerequisites.

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, destructiveHint=false, and idempotentHint=false, so the safety profile is covered. The description adds useful behavioral context by explaining the tool's role as a discovery mechanism for site IDs, and the schema enriches this with pagination details. Minor gap: the description does not explicitly state that results are paginated or that filters are optional, but the schema handles 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?

Two sentences with no fluff: the first identifies the resource and filters, the second states the primary use case. The most important guidance (site ID discovery) is front-loaded at the end of a short description. 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 read-only list tool with 100% schema coverage and no output schema, the description is sufficient. The only gap is that it does not state that the response is a list of site objects, but the tool name and schema make that evident. The description handles the main contextual need: routing the agent to use this tool for site ID discovery.

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 provides, but it does frame 'name' and 'subdomain' as filters and 'site ID' as the key output, which adds minimal semantic value. The pagination and sparse-fieldset parameters are already well documented 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?

The description states a specific verb ('List') and resource ('help doc sites (knowledge bases)'), and distinguishes this tool from related article tools by noting its purpose is to discover the site ID required by the help doc article tools. It is immediately clear what the tool does and how it differs from siblings like twdesk-get_helpdoc_site or twdesk-search_helpdoc_articles.

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 says 'Use this to discover the site ID required by the help doc article tools,' which tells the agent when to invoke this tool and for what downstream purpose. It does not name alternative tools to exclude, but the downstream guidance is strong and the distinction from article-level tools is clear.

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

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

Annotations already carry readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds only the filtering behavior by name or email and does not disclose return format, pagination quirks, or any additional side-effect context; this is acceptable but minimal, and there is no contradiction with annotations.

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

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

The description is two short sentences with the core action front-loaded and no filler. 'List inboxes' states the operation immediately, and 'Filter by name or email' adds essential scoping without wasting 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?

With a fully described seven-parameter schema and safety-bearing annotations, the tool is invokable from the structured data alone. Still, the description itself does not state what is returned or clarify when to prefer twdesk-get_inbox or twdesk-search_tickets, leaving a moderate contextual gap for a tool with 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 has 100% description coverage for all seven parameters, including pagination, ordering, and sparse fields. The description's mention of 'name or email' simply re-emphasizes two schema-documented filter parameters without adding new meaning, so 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 opens with the specific verb-resource pair 'List inboxes' and adds the filtering scope 'by name or email.' This clearly identifies a collection-listing operation and is easily distinguished from single-resource siblings such as twdesk-get_inbox, though it does not explicitly name or contrast any sibling.

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

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

The description implies use whenever an agent needs to enumerate inboxes and optionally filter them, and it names two concrete filter dimensions. However, it gives no explicit when-to-use vs. when-not-to-use guidance and does not reference alternatives like twdesk-get_inbox for single-inbox lookups.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds only that this lists and filters priorities, which is consistent with the annotations. It does not disclose additional behavioral traits such as pagination behavior, default ordering, or the shape of the returned list, but it does not contradict the annotations either.

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 very short and front-loaded: the core action is stated first, followed by the main filtering capability. Both sentences earn their place with no redundant filler. It is not wordy, though it is minimal enough that it leans on the schema for richer detail.

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

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

For a read-only list operation with well-documented parameters, the description is adequate for selection and basic invocation. However, there is no output schema, and the description does not mention pagination, field selection, ordering, or what a returned priority object contains. These gaps are partially covered by the schema, but the description itself leaves some operational context unspecified.

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 all seven parameters, so the schema carries the semantic burden. The description's 'Filter by name or color' does summarize two parameters but adds no new meaning beyond what the schema already states. Baseline 3 is appropriate because the schema is 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 starts with a specific verb and resource: 'List ticket priorities.' This clearly identifies the operation and distinguishes it from related tools like twdesk-get_priority, which retrieves a single priority, and twdesk-create_priority. The filter mention adds scope without confusing the core 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 as an enumeration/filtering tool, and 'Filter by name or color' suggests when filtering is relevant. However, it does not explicitly state when to use this tool versus alternatives such as twdesk-get_priority for a single record or twdesk-search_tickets for broader ticket search. Usage context is present but only by implication.

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 destructiveHint=false, so the agent knows this is a safe read operation; the description adds no behavioral detail beyond the filter capability. It does not contradict the annotations, and the pagination quirk (silent reduction above 100) is disclosed in the schema rather than the description. Acceptable given annotation coverage, but no extra behavioral context is contributed.

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 terse sentences with zero filler: 'List ticket statuses. Filter by name, color, or code.' The core action is front-loaded and every word earns its place. This is exemplary concision for a simple list tool.

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

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

For a read-only list tool with annotations covering safety and a schema covering all parameters, the description is mostly sufficient. However, with no output schema, the description does not clarify the response shape, and it omits behavioral nuances like whether multiple filter values are AND'd or OR'd, or how this relates to twdesk-get_status. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so every one of the 8 parameters is already documented with meaning. The description's mention of filtering by name, color, or code echoes three schema properties but adds no new semantics such as filter combination behavior or format expectations. Baseline 3 is appropriate since the schema carries the load.

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: 'List ticket statuses', followed by the three filter dimensions (name, color, code). This distinguishes it from sibling list tools like twdesk-list_tags, twdesk-list_priorities, and twdesk-list_ticket_types by naming a distinct resource. It stops short of a 5 because it adds no scoping detail (e.g., all vs. filtered, or workspace scope) that would sharpen the boundary against get_status.

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?

Usage is implied: the name and 'List ticket statuses' make it evident this tool enumerates statuses, and the filter clause hints at when filtering is relevant. However, there is no explicit when-to-use versus alternatives — notably twdesk-get_status for retrieving a single status — and no exclusions or routing guidance are provided.

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, destructiveHint=false, and openWorldHint=false. The description adds a pagination-related caveat via the pageSize parameter description (silent reduction of values over 100), which is useful behavioral context. No contradictions with annotations. However, no extra detail about response shape or filtering semantics beyond schema.

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 short and front-loaded with the primary action and resource—'List Desk tags'—followed by the key filter options. It earns a 4 rather than 5 because it omits the pagination caveat that appears in the schema and could have mentioned the orderBy/orderDirection options; yet what is there is efficient and free of 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 read-only list operation with all-optional parameters and full schema coverage, the description plus annotations cover the essential usage. It is not a 5 because the description itself is minimal: it doesn't mention that results are paginated, that all parameters are optional, or how to use fields/orderBy. With no output schema, the return format is left entirely to the agent's inference, which is acceptable for a simple list tool but not fully complete.

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

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

The input schema has 100% description coverage, so the schema already documents all eight optional parameters well, including the important pageSize caveat. The description's one-line filter list (name, color, inbox) is redundant with the schema but does reinforce the main filter dimensions. Baseline 3 is appropriate because the schema carries the heavy lifting and the description adds no meaningful supplementary parameter detail.

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: 'List Desk tags' followed by filtering dimensions (name, color, inbox). It clearly distinguishes from sibling tools like twdesk-get_tag (single entity retrieval) and twdesk-create_tag (creation). Slight deduction because it lists filter options rather than describing the full scope of what is returned, but purpose is clear.

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 listing/filtering tags, which is reasonably clear from the resource and filter parameters. However, it does not explicitly state when to prefer this tool over alternatives such as twdesk-get_tag or twdesk-search_tickets, nor does it mention any exclusions or prerequisites. The filter hints give context but no explicit selection guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that results can be narrowed by name or inbox, which is consistent with read-only behavior, but does not disclose additional runtime traits such as response shape or pagination behavior; the schema compensates for pagination 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?

Two short, front-loaded sentences with no filler or redundancy. The description is appropriately sized for a straightforward list/filter tool.

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

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

For a simple read-only list operation with a rich parameter schema and clear annotations, this description is mostly complete. Minor gaps are the lack of explicit return-shape information and alternative-tool routing, but the tool name and schema cover the essential invocation 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 description coverage is 100%, so the schema fully documents all seven parameters. The description only restates the name and inbox filters at a high level and does not add meaning beyond the schema, which is expected given the high coverage baseline.

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 ('List') and resource ('ticket types'), and mentions the key filtering dimensions. It is clear and distinct from singular get/update/create ticket-type tools, though it does not explicitly name any sibling 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?

The list verb implies an enumeration use case, and 'Filter by name or inbox' gives a concrete selection context. However, there is no explicit guidance about when to prefer this over twdesk-get_ticket_type or twdesk-search_tickets, leaving the distinction mostly implicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds scoping context but no further behavioral detail such as result shape, default ordering, or pagination behavior beyond what the schema already documents.

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 primary action is front-loaded, and the alternative tool is mentioned immediately, making it easy to scan and act on.

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

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

For a read-only list tool with a fully documented schema and clear annotations, the description covers the essential purpose and the key sibling distinction. It could be slightly more explicit about what a returned user record looks like, but the absence of an output schema makes that a minor gap rather than a critical one.

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%, with all 10 parameters documented in the schema itself. The description adds no parameter-level detail, but it does not need to because the schema already carries the full parameter burden.

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 operation ('List') and the resource ('support agents'), and disambiguates what 'users' means in this domain. It also names the sibling tool twdesk-list_customers as the correct tool for a different audience, making the purpose unmistakable.

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

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

The description explicitly tells the agent when not to use this tool: 'For customers, use twdesk-list_customers.' This is a clear, actionable routing instruction that prevents the most likely confusion with a similarly named sibling.

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 convey the destructive hint and non-read-only nature, so the description doesn't need to repeat that. It adds the useful distinction between customer-facing replies and internal agent notes, but does not disclose potential side effects such as email delivery or notification behavior 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?

Two short sentences with no filler; the core purpose is front-loaded and the threadType guidance earns its place as a high-value usage hint. This is an appropriately sized 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 relatively simple action with full schema coverage and annotations, the description covers the essential purpose and the key note-vs-message distinction. It could be slightly more explicit about how it differs from twdesk-update_ticket, but nothing critical is missing for invoking it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters fully. The description only repeats the threadType note guidance already present in the schema, adding no new semantic information beyond what structured fields provide.

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 ('Reply to a ticket') with a specific verb and resource, and the threadType note clarifies an important variant. It doesn't explicitly distinguish itself from twdesk-update_ticket, but 'reply' strongly implies sending a message/note rather than editing ticket fields.

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

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

The description gives helpful guidance for choosing threadType=note for internal agent notes, which is a clear within-tool usage rule. However, it does not mention when to use this tool versus alternatives like twdesk-update_ticket or other messaging tools, leaving tool selection partially implicit.

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

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

Annotations already establish a read-only, non-destructive safety profile, lowering the bar. The description consistently frames the tool as a filtered search but adds no behavioral context beyond the schema — no pagination defaults, empty-search behavior, or result-set semantics.

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

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

Two short sentences, front-loaded with the core action, followed by the key filter dimensions. There is zero filler — 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?

Adequate for a read-only search tool: annotations cover the safety profile, the schema covers all optional parameters, and the description states the core behavior. Gaps include no return-value description (no output schema) and no guidance distinguishing search from twdesk-get_helpdoc_article.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description's filter list (search term, status, site, category) largely restates schema content and adds no new meaning; page and pageSize are not even mentioned.

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') and resource ('help doc articles'), and enumerates concrete filter dimensions (search term, status, site, category). This distinguishes it from siblings like twdesk-get_helpdoc_article (single-article fetch) and twdesk-search_tickets (different resource), though it never names them explicitly.

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

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

No when-to-use guidance is given. The description never contrasts searching against fetching a single article (twdesk-get_helpdoc_article) or searching tickets (twdesk-search_tickets), and the only cross-reference ('Use twdesk-list_helpdoc_sites to discover') appears in the schema rather than the description.

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 goes well beyond the annotations by disclosing two non-obvious behaviors: full tickets are truncated in transit, and result/page totals saturate at 10000 while pages beyond that are rejected. It also discloses the 'id is always returned' invariant and pageSize silent reduction. These are exactly the kind of behaviors an agent needs to know to avoid being misled.

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

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

The description is compact and front-loaded with the core purpose and filters, then the important capacity/truncation warnings. The only minor inefficiency is some redundancy between the opening sentence and the 'fields' parameter description, both warning about truncation when returning whole records. But the message is important enough that repetition is defensible.

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 16-parameter read-only search tool with no output schema, the description covers all agent-critical context: when to use it, what filters are available, the performance/truncation trap, the 10000 saturation behavior, and the practical guidance to narrow filters rather than page deep. The schema documents every parameter and the description adds the behavioral context needed to use them safely.

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% but the description adds crucial semantics beyond the schema: it explains that a full ticket is huge and may be truncated, that fields avoids that, that 'id' is always returned, that pageSize values over 200 silently reduce, and that date filters operate on whole days. It doesn't enumerate every filter dimension twice, but it adds meaningful usage constraints that the schema alone would not convey.

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

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

The description opens with a clear verb and resource ('Search tickets') and then enumerates the distinct filter dimensions (inbox, customer, company, tag, status, priority, user, creation date range). It differentiates itself from sibling search tools like twdesk-search_helpdoc_articles and twprojects-search by being ticket-specific, and from twdesk-list_* filters by being a search with many filter dimensions.

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 tool is self-contained with explicit guidance on when to use it (searching/filtering tickets) and what to avoid: it warns against paging past 10000 results and tells the agent to narrow filters instead. Each filter parameter also names the sibling list tool to discover valid IDs. The 'omitMerged' parameter description explicitly explains when it is needed (merged tickets cannot be filtered by status).

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, but the description adds valuable context by clarifying that only the link is removed while the task and ticket remain intact. This prevents the agent from assuming the entities are deleted, going beyond the annotation's raw destructive flag.

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, precise sentence with no redundancy. Every word adds value, efficiently conveying both the action and the critical side 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 low-complexity destructive operation with two fully described parameters and no output schema, the description covers the essential effect. It could optionally mention idempotency or failure conditions (e.g., if the link doesn't exist), but given the annotations and schema, it is sufficient for correct invocation.

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

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

The schema provides 100% coverage for both parameters, each with clear descriptions and discovery hints (e.g., 'Use twprojects-list_tasks to discover'). The description adds no additional parameter semantics, which is acceptable given the schema's completeness, so the 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 clearly states the action ('Unlink') and the specific resources involved ('a Teamwork Projects task from a Desk ticket'), and adds the critical clarification that both entities are preserved. This uniquely identifies it as the inverse of twdesk-link_task_to_ticket, making it easy to distinguish.

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 indicates the operation but does not explicitly state when to use it versus alternatives, nor any preconditions (e.g., that the task must be currently linked). The name and inverse sibling suggest usage, but no explicit guidance is provided.

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 convey readOnlyHint=false, and the description only repeats the mutation by saying 'Update'. It adds no information about partial vs. full replacement, required permissions, validation behavior, side effects, or what is returned. Since it adds zero context beyond the annotations, this is under-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 short and front-loaded, but it borders on tautological: 'Update Desk company' essentially restates the tool name and title. It is concise in the sense of brevity, but under-specified for a 10-parameter mutation tool.

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

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

With 10 optional fields, no output schema, and no explanation of update semantics, a single sentence is not enough for an agent to correctly invoke the tool beyond guessing from the schema. The description does not compensate for the missing usage and behavior 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?

Schema description coverage is 100%, so all 10 parameters are already documented in the input schema. The description adds no parameter-level meaning, so the baseline of 3 applies; no penalty is warranted, but no credit beyond baseline either.

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

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

Description states a clear verb+resource: updating a Desk company. It is more specific than the title 'Update Company' by adding the product context, though it does not describe which aspects of the company can be changed or how it differs from twdesk-create_company/twdesk-get_company.

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

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

No guidance is provided about when to choose this tool over twdesk-create_company, twdesk-get_company, twdesk-list_companies, or the many other update_* siblings. An agent must infer from the tool name that it is for existing companies, which is 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 description only says 'Update customer' and adds no behavioral context beyond what the annotations already imply. Key information is missing, such as whether this is a partial update affecting only provided fields, what happens if the id does not exist, and whether the operation is reversible or auditable.

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

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

The description is extremely short and has no fluff, but it is under-specified rather than appropriately concise. A tool with 14 parameters and one required id would benefit from a sentence clarifying that this updates an existing customer with only the supplied fields.

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 and only sparse annotations, the description leaves significant gaps. It does not state that the customer must already exist, that updating is partial or full, what fields are commonly used, or what the caller should expect in response. The schema covers parameters, but operational context is missing.

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

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

Schema description coverage is 100%, so the parameter descriptions already explain each field and the 'id' requirement. The tool description adds no extra meaning, but this is acceptable because the input schema fully documents all 14 parameters.

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

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

The description names a clear verb and resource: 'Update customer.' This is enough to distinguish it from sibling tools like twdesk-update_company or twdesk-update_ticket by resource type. However, it does not mention what aspects of a customer can be updated, leaving the full purpose to be inferred from 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?

There is no guidance on when to use this tool versus alternatives such as twdesk-create_customer or twdesk-update_company. No prerequisites, partial-update semantics, or conditions are provided, so the agent must infer usage entirely from the name and schema.

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 separately indicate the operation is not read-only, not idempotent, and not destructive, but the description adds no behavioral context such as partial-update semantics, which fields are required at call time beyond id, or what happens on success. The phrase 'existing' only repeats the notion of modifying a current resource.

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?

One short sentence with no filler, front-loading the action and object. It earns its place, though it is sparse and close to the tool title.

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 straightforward update tool with rich parameter descriptions and safety annotations, the description is minimally adequate. However, with no output schema, it does not state what the tool returns, and it omits partial-update behavior, a meaningful gap 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?

The input schema has 100% description coverage, so the schema already documents all six parameters. The description itself adds no extra parameter meaning; it does not clarify that only id is required or that omitted optional fields are left unchanged.

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: 'Update an existing help doc article.' This clearly distinguishes it from twdesk-create_helpdoc_article, twdesk-get_helpdoc_article, and twdesk-search_helpdoc_articles.

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 word 'existing' implies this tool is for modifying an already-created article rather than creating a new one. However, it does not explicitly name alternatives or state when-not-to-use, leaving usage conditions largely 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?

Annotations already convey that this is a mutating, non-idempotent, non-destructive operation, and the description does not contradict them. The description adds little behavioral context beyond 'update', such as whether existing tickets using the priority are affected, but the annotation coverage prevents this from being a serious 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?

The description is a single sentence with no filler or redundancy. It is appropriately short for the tool's simplicity, though 'ticket priority' is slightly misleading and could have been phrased more precisely.

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

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

The description is too thin to resolve a key ambiguity: does it update a priority definition or change the priority on a ticket? Given the large sibling set and the existence of twdesk-update_ticket, this missing semantic context is significant. Schema coverage handles parameters, but the tool's core purpose is not fully clarified.

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%, with clear descriptions for id, name, and color. The description does not need to repeat parameter details, so 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 provides a verb and resource, but says 'ticket priority' rather than clarifying that this updates a priority definition (name/color). Because the parameters are name and color, the intended resource is the priority entity itself, not the priority field on a ticket. This ambiguity makes it hard to distinguish from twdesk-update_ticket.

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 twdesk-update_ticket, twdesk-update_status, or other update tools. There are no conditions, exclusions, or alternatives mentioned.

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 indicate this is a mutating action (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds no behavioral detail beyond the generic word 'update' — it does not mention partial-update semantics, whether only provided fields are changed, validation behavior, or what happens to tickets already using the status.

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

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

The description is extremely short, but it is under-specified rather than appropriately concise. 'Update ticket status' largely restates the tool's purpose and omits the field-level and contextual detail needed to avoid ambiguity.

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 an update tool, the description lacks clarity about what entity is updated and what effects the operation has. The schema covers parameters, but the description does not tie together the status definition concept, optional fields, or distinguish this from updating a ticket's status field. Given no output schema and no usage guidance, the description is only minimally adequate.

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

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

The input schema provides descriptions for all four parameters (id, name, color, displayOrder), giving 100% schema description coverage. The description adds no parameter-level meaning, but the coverage baseline applies, so this is adequate.

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 verb ('update') and a resource ('ticket status'), so it is not a tautology. However, 'ticket status' is ambiguous: it could mean updating a field on a ticket or updating a status definition entity. Given the schema exposes name, color, and displayOrder, it likely means the latter, but the description does not disambiguate this, nor does it distinguish itself from twdesk-update_ticket.

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 alternatives such as twdesk-create_status, twdesk-get_status, or twdesk-update_ticket. The description provides no context about prerequisites, exclusions, or scenarios where another tool would be more appropriate.

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

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

The description only restates that the tool mutates a Desk tag, which annotations already convey via readOnlyHint=false. It adds no context about side effects, permission requirements, partial-update semantics, or behavior when optional fields are omitted. It does not contradict the annotations, but it adds no behavioral value beyond them.

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

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

The description is a single short sentence with no filler, and the verb 'Update' is front-loaded. It is appropriately concise for a simple tool, though it provides no structural elaboration such as usage hints or caveats.

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 complete schema coverage and annotations, the description provides just enough to identify the target resource. However, it does not address when to choose this over sibling tag-update tools, nor does it describe update behavior beyond the schema. It is minimally viable but not fully complete.

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

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

Schema description coverage is 100%, and each parameter (id, name, color) already has a meaningful description. The tool description adds no parameter-level detail, but none is strictly needed because the schema fully documents the parameters. A 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 states a specific verb and resource: 'Update Desk tag.' The 'Desk' qualifier distinguishes this from sibling tools like twprojects-update_tag and twspaces-update_tag. An agent can immediately understand what the tool operates on.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives such as twprojects-update_tag or twspaces-update_tag. It does not state prerequisites, exclusions, or context in which this update operation should be preferred. The only signal is the 'Desk' qualifier, which is implied rather than explained.

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

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

Annotations already declare readOnlyHint=false, so the mutating nature is covered by structured metadata. However, the description adds no behavioral context beyond that — it does not disclose whether updates are partial or full replacement, whether changing status/agent triggers notifications, or what side effects occur. It neither contradicts the annotations nor enriches them.

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

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

Two words is under-specification, not conciseness. The description front-loads nothing useful since there is no information to front-load. It fails to earn its place as a meaningful tool 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 mutation tool with 12 parameters, no output schema, and nuanced semantics (partial vs. full update, required fields, tag add/remove behavior via tags vs. deleteTags), a two-word description is grossly inadequate. With no output schema, the description should at least clarify return value or side effects; it explains neither.

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

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

Schema description coverage is 100%, and the schema descriptions are genuinely helpful — they explain each field and even reference discovery tools (e.g., 'Use twdesk-list_tags to discover', 'Use twdesk-list_statuses to discover'). The description itself adds no parameter meaning, but the baseline of 3 applies because the schema does the heavy lifting.

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 'Update ticket.' is a tautology — it restates the tool name (twdesk-update_ticket) and title ('Update Ticket') verbatim. It names a verb and resource but adds no specificity about scope, semantics, or how it differs from siblings like twdesk-create_ticket, twdesk-reply_ticket, or the many other twdesk-update_* tools.

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 zero guidance on when to use this tool versus alternatives. It does not mention that twdesk-create_ticket is for new tickets, twdesk-reply_ticket for customer replies, or twdesk-get_ticket for retrieval. There is no when-to-use, when-not-to-use, or alternative routing — just the bare action statement.

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

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

The description adds no behavioral context beyond what the annotations already imply: it is an update operation and not read-only. It does not disclose whether the update is partial or full, whether an existing ticket type is required, what side effects occur, or what the response looks like. The negative annotation hints (idempotentHint=false, destructiveHint=false) do not compensate for this.

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

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

The description is extremely short with no wasted words, but it is under-specified rather than effectively concise. It basically restates the tool name and provides no structural or contextual value for an agent navigating among many sibling tools.

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 definition is incomplete for a mutating tool with no output schema. It lacks information about return values, side effects, and when to choose this tool over related update_* tools. The parameter schema helps, but the description leaves important context unaddressed.

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 already have individual descriptions. The tool description adds no parameter-level meaning, but since the schema carries the full burden, 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 states a clear verb ('update') and a specific resource ('ticket type'), so an agent can tell this modifies an existing ticket type rather than creating or listing one. It does not differentiate from sibling update tools like update_status or update_priority, but the resource name provides basic purpose 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?

There is no guidance on when to use this tool versus alternatives such as create_ticket_type, get_ticket_type, or update_ticket. No context, prerequisites, or exclusions are mentioned, so the agent must infer 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?

Beyond annotations, the description explains that references are single-use, that the returned numeric file ID is reusable, and that attaching a reference already files the file in the project. This is valuable behavioral context. It does not explicitly discuss duplicate handling or non-idempotency at a behavioral level, though auto_new_version and idempotentHint are present in structured data.

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?

Each sentence earns its place: purpose, workflow, return-value behavior, and usage guidance. The most important information is front-loaded, and there is no redundant or filler content.

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

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

For a tool with 10 parameters and no output schema, the description supplies the essential return type, the prerequisite workflow, and decision rules for when this tool is appropriate. Field-level details are fully covered in the schema, so nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the reference lifecycle, the reusable numeric file ID, and how the return value connects to attachment_file_ids on task creation/update, going beyond individual parameter descriptions.

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

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

The description opens with a specific action and resource: 'Store an uploaded file in a project's files area.' It clearly distinguishes this tool from alternatives by describing the upload prerequisite and contrasting it with attaching a reference directly to a task, comment, or message.

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 this tool: to store a file on its own, to describe or categorise it, or when it must reach more than one place. It also gives the workflow sequence: create_upload_url first, then pass the reference here, then use the returned file ID in attachment_file_ids.

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 indicate this is a mutating, non-destructive, non-idempotent operation. The description adds the specific action of adding a user to a project but does not disclose extra behavioral context such as whether permissions are required, what side effects occur, or how repeated calls behave. With annotations covering the basic safety profile, this is minimally adequate.

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 or redundant information. Every word earns its place, and the core action is stated immediately.

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 two-parameter tool with full schema coverage, the description is mostly sufficient. However, it does not explain the optional nature of user_ids or what happens when it is omitted, and there is no return-value guidance since no output schema exists. The description could be more helpful but is not severely incomplete.

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

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

Schema description coverage is 100%, so the schema already documents project_id and user_ids adequately. The description does not add further meaning, and its singular phrasing ('a user') could slightly conflict with the array type of user_ids, but the schema clarifies this.

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 ('Add') and resource ('a user to a project'), clearly identifying the operation. It differentiates from sibling tools like add_project_file and create_user by specifying the project membership context. Even without mentioning 'member' explicitly, the intent 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 is provided about when to use this tool versus alternatives, such as create_user for new users or list_users for finding user IDs. There is no mention of prerequisites, exclusions, or conditions under which another tool should be preferred.

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 indicate this is a write operation (readOnlyHint=false) and not destructive. The description adds the dual-mode behavior (cloning vs template instantiation) but does not disclose side effects such as what gets duplicated, whether timers/members are copied, or how template mode is triggered. No annotation contradiction exists.

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 words. It immediately presents the action and the two use cases, making it easy to parse.

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

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

With 9 parameters, two boolean mode switches, and no output schema, the high-level description is thin. It does not explain how an agent should indicate template vs project copying, what is returned, or what the clone includes. The schema compensates, but the description alone is not a complete entry point.

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% with rich per-parameter detail, so the tool description does not need to restate parameters. The description adds no parameter-level meaning beyond the schema, matching the baseline 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 names a specific action (clone/copy/instantiate) and resource (project), and the two modes (copy existing, instantiate from template) are distinct enough to separate it from create_project. It clearly tells an agent what the tool does at a glance.

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