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

No annotations are provided, so the description carries the full burden. It states 'WRITE' to signal mutation, explains the default internal-note behavior, and warns that public=true is for customer-visible replies. It also specifies the exact API call, adding transparency. It does not mention permissions or side effects beyond visibility, but such details are not essential here.

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 starting with 'WRITE' and provides the core information without waste. The inclusion of the API endpoint is concise and useful.

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

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

There is an output schema (not shown), so return values are already covered. The description sufficiently covers the write nature, default behavior, and the caution about public visibility. It is complete enough for an agent to select and invoke the tool correctly, though it could optionally mention authentication prerequisites.

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 covers only 33% of parameters (only public has a description). The tool description does not explicitly explain body or ticket_id, though their names are self-explanatory. It does add context to public by saying 'set public=true only to send a customer-visible reply,' which reinforces the schema description. Overall, it adds some semantic value but does not fully compensate for the low 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 'Add a comment to a ticket' with a specific verb and resource, and includes the HTTP endpoint (PUT /api/v2/tickets/{id}). This distinguishes it from sibling tools like create_ticket, update_ticket, and get_ticket_comments by specifying the exact action.

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

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

Provides explicit guidance: 'Defaults to an internal note; set public=true only to send a customer-visible reply.' This tells the agent when to use the default vs. the public flag. It doesn't name alternative tools but the context is clear for this operation.

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

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

No annotations are provided, so the description carries the burden. It discloses 'WRITE' (mutation) and 'Idempotent,' which is meaningful behavioral context beyond a simple create/update. However, it omits details like permission requirements, reversibility, or what happens with null external_id.

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

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

The description is a single sentence, front-loaded with 'WRITE,' and contains zero filler. Every word contributes to understanding the tool's purpose and behavior.

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 core logic is clear and an output schema exists, so return values need not be explained. However, the description does not address edge cases like null external_id, multiple matches, or the uniqueness constraint on name, leaving some gaps for a 5-parameter mutation tool with no annotations.

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

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

Schema description coverage is only 60%, leaving tags and notes undocumented in both schema and description. The tool description itself does not add any parameter meaning beyond what the schema already provides, failing to compensate for the gaps.

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

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

The description clearly states the tool's action: 'Create an organization, or update it if one matches by external_id.' It specifies the resource (organization) and the distinguishing upsert behavior, setting it apart from sibling tools like create_or_update_user.

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

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

The description implies when to use the tool (when you want to create or update an org by external_id) and notes idempotency, which is a strong usage hint. It does not explicitly name alternatives or exclusions, but the context is clear given the 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?

With no annotations, the description carries the burden of disclosing side effects. It openly labels the operation as WRITE, notes idempotency, and states the deduplication rule ('cannot create duplicates'). It does not specify whether update replaces all fields or only provided ones, which is a notable gap, but the core behavioral traits are well covered.

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

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

The description is two sentences long, front-loaded with the WRITE label and action, and every phrase adds value. It efficiently conveys purpose, matching criteria, endpoint, and idempotency without redundancy.

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

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

Given the output schema exists and the tool handles a common upsert pattern, the description covers the essential purpose, matching keys, and safety properties. It falls short only in not clarifying update semantics for omitted fields, which is a meaningful but not fatal omission for this complexity level.

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

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

Schema description coverage is only 17%, so the description must compensate. It adds meaning by identifying email and external_id as matching keys, and it implies the upsert logic. However, it does not explain the roles of name, role, phone, or organization_id beyond their obvious names, leaving several parameters under-documented.

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

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

The description clearly states the tool's verb and resource: 'Create a user, or update it if one already exists' with a specific endpoint. It distinguishes itself from siblings like get_user and search_users by describing upsert semantics and matching keys (email or external_id).

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

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

The context is clear: use this tool to create or update a user based on email or external_id, and the idempotency guarantee is stated. However, it does not explicitly mention when not to use it or provide named alternatives, though the sibling list makes the distinction 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?

No annotations are provided, so the description must disclose behavioral traits. It only indicates it's a write operation via 'WRITE' and 'POST', but doesn't explain permissions, side effects, auto-creation of users, or response behavior. This is minimal.

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

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

The description is one sentence, front-loaded with 'WRITE:' and the action. Every word is purposeful, 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?

Despite having an output schema, the description is overly terse for a create operation with 7 parameters and no annotations. It omits context about required permissions, side effects (like auto-creating the requester user), and any operational caveats.

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

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

The description adds no parameter semantics. Schema coverage is only 29%, and the description doesn't compensate, leaving most parameters (tags, type, subject, priority, assignee_id) without explanatory context beyond their names.

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

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

The description clearly states the tool's function ('Create a new ticket') with a specific verb and resource, and includes the HTTP endpoint. It distinguishes from siblings like update_ticket and add_ticket_comment.

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

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

No guidance on when to use this vs. alternatives; the description only provides a terse statement and endpoint without mentioning update_ticket or any conditions.

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 discloses that the tool returns the full HTML body, which is a useful behavioral detail. It also shows a GET method, implying a read-only operation, but with no annotations it does not address auth, rate limits, or error behavior. The description carries only some of the transparency burden.

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 that front-loads the action and resource, followed by the endpoint. Every word earns its place, with no unnecessary elaboration.

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

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

Given the tool's simplicity—one parameter, an output schema, and a straightforward GET operation—the short description is largely sufficient. It covers the core purpose and response content, though it omits error handling or comparison to search_articles, which would be nice but not essential.

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 defines article_id as an integer with no description, and the description does not explicitly explain the parameter. However, the endpoint includes {id}, and the parameter name is self-explanatory, so the description adds minimal contextual meaning beyond the schema. For a single obvious parameter, 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 clearly states 'Get one Help Center article' with a specific verb and resource, and includes the full HTTP endpoint. It distinguishes itself from search_articles by specifying a single article by ID, making the purpose unambiguous.

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

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

The description implies usage when you have a specific article ID, and the endpoint reinforces that. However, it does not explicitly contrast with search_articles or state when not to use this tool, so guidance is implied rather than explicit.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the operation is a read-only GET request, which is useful context, but it does not disclose any error conditions, authentication requirements, or other caveats beyond the basic retrieval action.

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. The API path is included without any wasted words, making it highly concise and well-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 description covers the essential purpose and endpoint, and the presence of an output schema handles return value documentation. However, it lacks explicit guidance on when to use this tool versus sibling tools, which is a minor gap given the tool's simple nature.

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 shows a single required integer 'ticket_id' with no description. The description's REST path 'tickets/{id}' implies that the parameter is the ticket's unique identifier, adding a small amount of semantic meaning. Since there is only one obvious parameter, this minimal linkage is sufficient but not rich.

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 'Get full details of one ticket', which uses a specific verb and resource, clearly distinguishing it from sibling tools like search_tickets (multiple tickets) and create/update tools. The inclusion of the REST endpoint (GET /api/v2/tickets/{id}) further clarifies the action and resource.

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

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

The description implies usage when you need complete details of a specific ticket, but it does not explicitly state when to use this tool over alternatives like get_ticket_comments or search_tickets. No when-not-to-use scenarios or alternative recommendations are provided, leaving the context 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?

With no annotations, the description carries the behavioral burden. It discloses that both public replies and internal notes are included and that results are ordered newest first. It also provides the API endpoint, giving additional context about execution. This goes beyond merely stating 'get comments'.

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, well-structured sentence that front-loads the purpose. It is concise with no filler or redundant information. Including the API endpoint adds useful context without unnecessary length.

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 and the presence of an output schema (not shown), the description adequately covers the core behavior: retrieving a conversation thread with public and internal notes, newest first. It does not mention pagination behavior beyond the schema, but the schema already includes per_page defaults. Overall, the description is sufficient for the tool's complexity.

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

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

The schema has 2 parameters with 0% description coverage, so the description must compensate. While the endpoint path '/api/v2/tickets/{id}/comments' implicitly maps 'id' to 'ticket_id', the 'per_page' parameter is completely unexplained, including its default and max values. The description adds minimal insight beyond the raw parameter names.

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

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

The description clearly identifies the action ('Get') and resource ('conversation thread of a ticket'), and specifies the contents ('public replies and internal notes') and ordering ('newest first'). This distinguishes it from sibling tools like 'get_ticket' (likely ticket details) and 'add_ticket_comment' (writes).

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

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

The description provides clear context: use this to retrieve the comment thread for a ticket. It does not explicitly mention alternatives or exclusions, but the wording 'Get the conversation thread' implies the appropriate use case. There is no misleading 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?

No annotations are provided, so the description carries the full burden. It discloses the HTTP method (GET), implying a safe read operation, and explains the intended purpose. However, it does not address behaviors like 404 responses or authorization, though for a simple read-by-ID tool this is a minor 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?

Two sentences, front-loaded with the core purpose, followed by a practical use case. No redundancy or filler; every word contributes to understanding the 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?

Given the tool's simplicity (one integer parameter, GET operation) and the presence of an output schema, the description is complete. It provides the endpoint, purpose, and use case without needing to explain return values. No further context is necessary for an agent to use it correctly.

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

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

The schema has 0% description coverage, so the description must add meaning. It clarifies that the user_id parameter corresponds to requester_id/assignee_id values from tickets, linking the parameter to its real-world usage. The endpoint template also confirms the parameter mapping, adding value beyond the bare schema.

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

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

The description clearly states 'Get a Zendesk user by ID' and includes the exact REST endpoint, making the operation unambiguous. It distinguishes itself from sibling tools like search_users by emphasizing ID-based lookup and connecting it to ticket tool outputs.

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 'Use to resolve requester_id / assignee_id values returned by ticket tools' gives a specific, practical context for when the tool should be used. It does not explicitly name alternatives or exclusions, but the guidance is clear enough to prevent misuse with search 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?

With no annotations, the description must carry the behavioral transparency burden. It discloses that the tool returns all tickets for an organization and identifies the 'account-health view', but it does not mention pagination behavior, authentication needs, rate limits, or how the result is structured. This is minimal but meaningful context beyond a tautology.

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 key information front-loaded. Every clause adds value: the first defines scope and purpose, the second provides a usage prerequisite. No redundancy or 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 list operation with an output schema present, the description is largely complete: it gives purpose, scope, and a prerequisite workflow. The only notable gap is that it does not explain pagination behavior or warn about potentially large result sets, but the page/per_page parameters and output schema partially cover this.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It explains how to obtain organization_id via search_organizations, but page and per_page are left entirely to the schema's defaults and bounds without any added context about their practical use. This is only partial compensation for one of three 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 clearly states the action (List), the resource (tickets), and the scope (all tickets of one organization). It also names the endpoint and distinguishes this tool from siblings like search_tickets by emphasizing the organization-level account-health view.

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 instructs the agent to call search_organizations first to obtain the organization_id, providing a clear prerequisite workflow. It does not explicitly state when not to use this tool versus search_tickets, but the 'all tickets of one organization' scope gives strong contextual 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?

No annotations are provided, so the description carries the burden. It mentions 'by relevance' and the GET method, implying a read-only search operation, but does not explicitly state that it is non-destructive or discuss rate limits or other behavioral traits. Some transparency is provided, but not comprehensive.

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

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

The description is two sentences: the first identifies the action and endpoint, the second provides usage guidance. It is concise, front-loaded, and every sentence earns its place.

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

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

The tool is simple, an output schema exists, and parameters are reasonably self-explanatory. The description sufficiently supports selection and invocation, though it lacks explicit mention of pagination or ordering behavior, which is not critical given the 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 67% (query and locale have descriptions), and the description adds 'by relevance' which relates to query semantics. However, it does not detail per_page or locale behavior beyond the schema. With moderate schema coverage, the description offers minimal additional parameter meaning.

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 clearly identifies the resource as 'Help Center knowledge base articles', distinguishing it from sibling tools like search_tickets and search_users. The HTTP GET endpoint further clarifies the exact API.

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 explicit context: 'Use before answering questions that the knowledge base may already cover.' This tells the agent when to invoke this tool, though it doesn't explicitly mention alternatives or when not to use it.

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

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

The description explicitly states the HTTP method (GET) and the return behavior ('Returns organizations whose names begin with...'), conveying a read-only operation. It adds useful context about prefix matching beyond the schema, though it does not discuss pagination or 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?

Two sentences, front-loaded with the action, includes the endpoint and precise matching rule. No redundant information, making it highly efficient.

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

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

For a simple one-parameter search tool with an output schema, the description covers the core purpose and matching behavior. Minor gaps like case sensitivity or pagination are not critical for basic 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 description for 'name' is somewhat vague ('Organization name or its beginning'), but the tool description clarifies that the parameter is the prefix for matching. This adds meaningful semantics beyond the schema, and the schema coverage is 100%.

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 uses specific verb 'find' with resource 'organizations' and clarifies the matching behavior ('names begin with the given value'). It clearly distinguishes itself from sibling tools like search_users by scoping to organizations.

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

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

The description clearly implies the tool is for searching organizations by name prefix, providing clear context for when to use it. However, it does not explicitly mention alternatives or exclusion cases, 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?

No annotations are provided, so the description carries the burden. It discloses key behavioral traits: 'Returns slim tickets' and 'API caps results at 1000 per query', which are important for expectation-setting. It does not cover authentication or rate limits but provides meaningful context beyond the 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 three sentences, front-loaded with purpose, followed by usage guidance and limitation. Every sentence contributes unique value without redundancy, making it highly concise and well-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?

Given the output schema exists, the description need not explain return values. It covers purpose, usage, and a key API limitation. However, it omits details about pagination behavior and sort options, which could be important for complex queries. Still, the schema partially compensates, making the overall description reasonably 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 only 25% (only the query parameter is described), and the tool description does not compensate. It mentions 'date ranges' as a narrowing strategy but does not explain page, per_page, or sort_by meaning or usage. The defaults and enum in the schema are present, but the description adds little semantic value for the undocumented 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 begins with 'Search tickets' and includes the endpoint 'GET /api/v2/search', clearly identifying the action and resource. It differentiates from sibling search tools by focusing on tickets and explicitly references get_ticket / get_ticket_comments for detail, establishing a distinct 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?

Explicitly instructs to 'Use this first to find tickets, then get_ticket / get_ticket_comments for detail', providing clear when-to-use guidance and naming alternatives. Also advises to narrow with date ranges when needed, covering a practical usage scenario.

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

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

No annotations are provided, so the description carries the full burden. It discloses the method (GET), indicating a read-only operation. However, it does not mention additional behavioral aspects such as pagination, result limits, authentication requirements, or whether partial matches return multiple results. Some transparency is provided via the HTTP method, but not comprehensive.

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

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

The description is a single sentence that front-loads the primary action and includes the endpoint as supplementary context. It is succinct and every element serves a purpose, with no filler or redundancy.

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

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

The tool is simple (one parameter) and has an output schema, so return values are covered by the schema. The description identifies the search criteria and endpoint. It does not mention potential edge cases (e.g., exact vs fuzzy matching), but given the output schema and simplicity, it is sufficiently complete.

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

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

The schema description coverage is 100% with the 'query' parameter described as 'Name, email, or partial match'. The tool description largely repeats this information ('by name or email') without adding extra meaning. The baseline of 3 applies because the schema already documents the parameter thoroughly.

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 ('Search users') and the query criteria ('by name or email'). It also includes the HTTP method and endpoint (GET /api/v2/users/search), which adds specificity. This distinguishes it from sibling tools like get_user (retrieval by ID) and search_organizations.

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

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

The description implies when to use the tool (when searching by name/email) but does not explicitly state exclusions or alternatives. No mention of 'use get_user for exact ID lookup' or 'for organization search use search_organizations'. Usage guidance is implied but not explicitly contrasted with 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?

With no annotations provided, the description must carry the behavioral burden. It does label the operation as 'WRITE' and states the HTTP method, but it does not disclose whether fields are merged or fully replaced, nor what happens when a field is set to null. It does explicitly note the non-comment behavior, which is useful, but leaves other side effects unstated.

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, front-loaded with the operation type ('WRITE') and a clear list of fields. It wastes no words and provides the key differentiator in the second sentence.

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 an output schema and a sibling list, the description is largely sufficient. It gives the endpoint, the fields, and the key exclusion (comments). The main gap is the lack of explanation about merge-vs-replace semantics and null handling, which could affect usage, but the schema's tag description partially covers one aspect.

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

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

Schema description coverage is only 20% (only the 'tags' parameter has a description in the schema), so the description is expected to compensate. It mentions the field names 'status, priority, assignee, tags' but does not explain their semantics, types, or accepted values. There is also a mismatch: the description says 'assignee' while the schema parameter is 'assignee_id', and it does not clarify that this is a user ID, nor does it describe the enum values for status/priority.

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 ('Update') and resource ('ticket fields: status, priority, assignee, tags'), and clearly distinguishes what it does from the sibling tool add_ticket_comment by explicitly stating 'Does not add comments' and directing to that alternative. It also states the HTTP method and endpoint, making the function unambiguous.

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

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

It clearly states when to use the tool (to update ticket fields) and explicitly states when not to use it (for adding comments), providing the exact sibling tool to use instead (add_ticket_comment). This gives both an inclusion and exclusion criterion, which is strong guidance.

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