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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, covering safety and repeat-call behavior. The description adds one genuinely useful behavioral constraint — the target must be a *manual* group — but says nothing about what happens on duplicate membership or against a dynamic group.

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 zero waste. It is not padded, though its brevity shades into under-specification rather than tightness.

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?

Output schema exists and annotations cover safety, so return values need not be explained. Still, for a membership mutation the description omits error conditions (dynamic group, unknown requester) that an agent would want before calling.

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 both parameters are documented (albeit thinly: 'Requester ID', 'Requester group ID'). The description adds no format, sourcing, or lookup guidance beyond the schema, so 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?

States a specific verb (add) and resource (requester to a requester group), and the qualifier 'manual' narrows scope meaningfully. It implicitly contrasts with remove_requester_from_group, but never names siblings or clarifies how it relates to dynamic groups.

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, no prerequisites, no mention of the sibling remove_requester_from_group or list_requester_group_members as the counterpart operations. The agent must infer invocation conditions entirely.

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 destructiveHint=false, idempotentHint=true and readOnlyHint=false, so safety is partly covered. However the description adds nothing: it does not say what happens to the requester record after conversion, whether ticket history or group memberships carry over, or what permissions are required for a mutation flagged openWorldHint=true.

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?

It is a single efficient sentence with nothing wasted, but the brevity is under-specification rather than discipline: the most load-bearing term, 'occasional agent', is never explained.

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?

An output schema exists, so return values needn't be described, but for a mutating conversion tool operating on a requester the description leaves the core semantic question unanswered: what an occasional agent is and what state change the requester undergoes.

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 a single required requester_id, so the baseline is 3. The description contributes no additional meaning about the parameter or about how an 'occasional' agent differs from a regular one.

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 verb 'Convert' and the direction 'requester into ... agent' are clear, but 'occasional agent' is undefined terminology and the description never distinguishes this from sibling tools like create_agent or update_agent, which could plausibly achieve similar-looking outcomes.

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 rather than create_agent or reactivate_requester, and no prerequisites or exclusions are mentioned. The agent must infer the selection criteria 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 cover the safety profile (non-read-only, non-idempotent, non-destructive, open-world), so those need not be repeated. The description adds genuinely new behavioral context by stating the sign-in dependency on role assignment, which the schema does not encode. It remains silent on other meaningful behaviors for a write tool: duplicate-email handling, whether an invitation is sent, and 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?

Two short sentences with no filler, and the core action is front-loaded. For a 15-parameter mutation tool it is arguably over-terse rather than bloated, which costs a point on structure.

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 15 parameters, 47% schema coverage, and no annotation detail beyond hints, the description does not do enough to make the tool safe and correct to call. An output schema exists, so return values are covered, but error conditions, invitation behavior, and the semantics of most optional fields are all absent.

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 only 47% across 15 parameters, so the description would ideally carry more weight. It does contribute one important nuance — that roles is effectively required despite the schema marking only first_name and email as required — but says nothing about the remaining undocumented fields (time_zone, reporting_manager_id, department_ids, observer_of, occasional).

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 and resource ("Create an agent"), which is unambiguous on its own. However, it does nothing to distinguish itself from siblings in an overlapping cluster such as create_requester and convert_requester_to_agent, so an agent must already know which one it wants.

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 second sentence gives a real invocation prerequisite (at least one role, tied to sign-in), which is useful. It offers no when-to-use versus when-not-to-use guidance and never names the close alternatives (create_requester, convert_requester_to_agent), leaving the tool-selection decision 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=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so safety and world-interaction are covered. The description adds nothing beyond that — no mention of the parent link being required, permission requirements, or what happens if the parent is closed or missing.

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 the scoping condition front-loaded. Efficiently written; the issue is under-specification rather than bloat.

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?

An output schema exists and every parameter is documented, which lightens the burden, but for an 11-parameter mutation tool the description says nothing about inheritance from the parent, required permissions, or post-creation effects. 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%, including enum-like value explanations for source, status, priority, so the baseline is 3. The description adds no meaning beyond the schema — for example it does not clarify when to use email vs requester_id, or how group_id/responder_id interact with the parent ticket's assignment.

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 (create) and resource (child ticket) and adds the key qualifier 'under an existing parent ticket', which distinguishes it from the sibling create_ticket. It stops short of explaining what a child ticket is in this system, but the core action is unambiguous.

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

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

No guidance on when to use this instead of create_ticket, no prerequisites about the parent ticket's existence/state, and no note on whether child tickets inherit parent fields. The agent must infer the selection criteria from the name alone.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds nothing about side effects (e.g. how members/observers are attached, what happens on duplicate names, whether escalation settings require business hours) and 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?

One short sentence with zero waste, but it is under-specified rather than genuinely concise. Nothing is front-loaded beyond the bare verb and resource.

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 10-parameter creation tool with openWorldHint=true and a rich set of grouping/escalation options, a one-line description is far too thin. It leaves the agent to infer intent, member provisioning, and aliasing behavior entirely from 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 100% with 10 well-annotated parameters, so the schema carries parameter meaning entirely. The description adds no clarification, for example about the ambiguity between 'members' and 'agent_ids' being aliases, which is exactly the kind of thing a description could have resolved.

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 is a verbatim restatement of the tool title 'Create agent group' and adds no scope detail. It does not distinguish this from the closely-named sibling create_requester_group, so an agent scanning names alone has no basis to pick correctly.

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 when-to-use or when-not-to-use guidance, no mention of the create_requester_group alternative, and no prerequisites such as whether agents referenced by agent_ids must already exist. The single sentence offers nothing beyond the 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 declare this is a non-readOnly, non-idempotent, open-world, non-destructive write, so safety is covered. The description adds the cross-field contact requirement, which is real behavioral context the annotations cannot express. It says nothing about duplicate handling, whether the requester is auto-added to groups, or side effects.

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

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

Two short sentences, action stated first, constraint second. Nothing is padded or repeated from the schema.

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 17 optional parameters and a write operation, the description covers the one hard rule an agent could trip over. Output schema exists, so return values need not be explained. However, it omits anything about duplicate detection, group membership side effects, or the relationship between first_name requiredness and the contact rule.

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 82%, so the baseline would be 3. The description earns an extra point by stating the OR-constraint across primary_email, work_phone_number and mobile_phone_number — a cross-parameter rule JSON Schema cannot express here (only first_name is in 'required'). This is genuinely additive for a 17-parameter tool.

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

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

States a specific verb and resource ('Create a requester'), which is unambiguous against siblings like create_agent or create_ticket. It stops short of explicitly distinguishing when a person should become a requester rather than an agent, but the resource itself 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 on when to use this versus create_agent, add_requester_to_group, or convert_requester_to_agent — all present in the sibling list. The only conditional content is a parameter constraint, not usage context.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so safety is covered. The description adds nothing beyond that: it does not say whether duplicates are rejected, what the manual vs rule_based membership implications are, or what is returned on 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?

A single front-loaded sentence with zero waste, but its brevity is under-specification rather than discipline. It earns its place only as a label, not as guidance.

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?

An output schema exists so return values need no explanation, but this is a creation tool with a meaningful manual/rule_based branching behavior (conditions only relevant for rule_based) that the description never surfaces. For a 4-parameter create operation, the description is too thin to be 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%, including the manual/rule_based enum and an example conditions payload, so the schema carries parameter meaning. The description adds no parameter context of its own; baseline 3 applies when the schema does all the work.

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 restates the tool name and title verbatim ('Create a requester group') with no added detail. It does convey a write verb and the resource, but it gives an agent nothing to distinguish it from siblings like create_group, create_requester, or update_requester_group.

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 when-to-use guidance, no mention of alternatives (create_group vs create_requester_group), and no prerequisites such as required permissions. The agent must infer everything from the 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 declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: it doesn't say what the call actually produces (presumably a ticket/request record), whether retries create duplicates, or how custom_fields and child_items affect behavior.

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

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

A single front-loaded sentence with zero waste. It is efficient, though the brevity borders on under-specification for a 6-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?

This is a non-idempotent, open-world write operation, and the description gives no indication of the resulting object or the effect of the optional bundling and custom-field parameters. The output schema and full param coverage help, but a one-line description leaves an agent without the operational context needed to invoke this confidently.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema and the baseline of 3 applies. The description only echoes 'catalog item', which loosely maps to display_id, and adds no semantics for quantity, requested_for, child_items, or custom_fields.

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 ('place a service request for a catalog item'), which is more informative than the title alone. It does not, however, distinguish this tool from near-siblings like create_ticket or create_child_ticket, so an agent must infer the boundary itself.

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

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

There is no explicit guidance on when to use this versus create_ticket, no stated prerequisites (e.g., that display_id must come from list_service_items/search_service_items), and no exclusions. Usage is only implied by the word 'catalog item'.

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 readOnly=false, destructive=false, idempotent=false and openWorld=true, so the safety profile is known. The description adds real value by stating the default outcome is a draft (not live content), but omits what happens on duplicate titles, whether folder_id must reference an existing solution folder, and any content-format requirements.

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 filler; the most decision-relevant fact (draft by default) comes first. It is efficient but verges on under-specified for an 8-parameter creation 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 create tool with 8 parameters, 3 required, and dependencies such as an existing folder_id, one sentence leaves significant gaps. The presence of an output schema removes the need to explain return values, but the description still doesn't cover required-field expectations or the distinction between draft and published flows.

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 75% with status, description, folder_id and review_date already documented in the schema. The description only echoes the status semantics ('draft unless status is 2') and adds nothing about article_type, tags, keywords, or the HTML body requirement.

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

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

Names a specific verb and resource (create a knowledge-base article) and clarifies the important nuance that the result is a draft unless status is 2. It is distinguishable from create_solution_folder/create_solution_category by resource, though it never explicitly contrasts with publish_solution_article.

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 parenthetical implies the normal path is draft creation and that publishing is opt-in via status=2, which is implicit usage guidance. There is no explicit when-to-use/when-not guidance, no mention of using publish_solution_article for existing drafts, and no prerequisite noted for folder_id.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the agent knows this is a non-idempotent write. The description adds nothing beyond that: no mention of required permissions, whether the name must be unique, whether categories can be nested, or whether a duplicate call creates a second category (relevant given idempotentHint=false).

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 short, front-loaded sentence with zero filler. It is efficient, though the brevity reflects under-specification rather than disciplined density.

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 in an open-world, non-idempotent context, the description omits uniqueness/validation rules, naming constraints, and organizational semantics of a knowledge-base category. An output schema exists so return values need not be explained, but the front-end behavior of the call is left bare.

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 67%: 'name' and 'workspace_id' carry their own descriptions, including the workspace default behavior. The 'description' parameter has no schema description and the tool description does not compensate, so one parameter's semantics remain undocumented.

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 and resource ('Create a knowledge-base category'), which is clear enough to distinguish from sibling reads/writes like update_solution_category or delete_solution_category. It does not explicitly differentiate category creation from the adjacent create_solution_folder or create_solution_article, leaving the taxonomy implicit.

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 versus creating a folder or article, no prerequisites, and no mention of what a category is used for in organizing articles. The agent must infer the entire usage context 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 declare that this is a non-read-only, non-idempotent, open-world creation operation. The description adds no behavioral context beyond the basic action, such as permission requirements, effects of visibility settings, or whether creating a folder affects existing articles.

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 concise, though its brevity contributes to gaps in guidance and behavioral context.

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

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

For a mutation tool with eight parameters, conditional visibility rules, and parent-folder nesting, the one-sentence description is insufficient. Although an output schema exists and the input schema is well documented, the description should do more to explain the tool's role and operational 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 high at 88%, so the schema already documents most parameters, including conditional requirements for group_ids, department_ids, and requester_group_ids. The description adds no additional meaning beyond what the schema provides, which matches the baseline of 3 for high-coverage schemas.

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: creating a knowledge-base folder. It is clear enough to distinguish from siblings like create_solution_article or create_solution_category, but it does not explicitly differentiate itself or clarify the 'solution' vs 'knowledge-base' terminology.

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_solution_category or create_solution_article, nor any mention of prerequisites, parent-folder nesting, or visibility requirements. The agent is left to 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 already declare the write, non-idempotent, non-destructive, open-world profile, so the baseline is lower. The description adds real value by disclosing that some ticket forms impose conditional mandatory fields and how to recover from missing_field. It does not disclose side effects such as requester notifications or what happens to defaults like source/status/priority.

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, no waste, with the core purpose front-loaded and the conditional requirement caveat following. Every clause conveys actionable 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?

An output schema exists and the 26-parameter schema is fully documented, so the description need not explain returns or field formats. The conditional-required and error-recovery notes cover the main ambiguity for this tool; missing is any mention of downstream effects (notifications, SLA timers) on ticket creation.

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

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

With 100% schema coverage the baseline is 3, and the schema already documents enum-like value lists (source, status, impact) and attachment restrictions. The description adds meaning the schema cannot: that group_id, responder_id, category and custom fields may become mandatory depending on the form in use, which changes how an agent should populate them.

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 and resource ('Create an incident or service-request ticket'), which is more precise than the title 'Create ticket'. It does not, however, distinguish itself from nearby siblings like create_child_ticket or create_service_request, so an agent must infer the boundary.

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 one explicit routing rule: consult get_ticket_fields when the API reports missing_field, which is genuinely useful error-recovery guidance. But there is no guidance on when to choose this over create_child_ticket or create_service_request, which are the closest alternatives.

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, idempotentHint=false, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds only the private-default behavior, which is already documented in the schema, and says nothing about notification side effects, deduplication, or attachment constraints beyond what structured fields 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?

A single front-loaded sentence with no filler; the default behavior is stated up front. It is efficient, though terse for a 7-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 an output schema, full schema annotation, and safety annotations present, the description doesn't need to explain returns. However, for a mutation that can notify requesters and attach files, it omits key operational context such as note-versus-reply routing and notification behavior.

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 is well documented (body HTML, private semantics, attachment limits, notify_emails). The description adds no parameter-level information beyond the schema, so 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?

States a specific verb and resource ('Add a note to a ticket') plus a meaningful default ('private by default'), so the action is unambiguous. It does not distinguish itself from siblings like send_ticket_reply or update_ticket_conversation, which an agent could easily confuse it with.

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 'private by default' parenthetical implies an internal-only note, which hints at usage, but there is no explicit when-to-use or when-to-prefer-send_ticket_reply guidance. Usage must be inferred.

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, idempotentHint=false, and destructiveHint=false, so the safety profile is covered, but the description adds nothing beyond the title. It does not warn that repeated calls create duplicate entries (non-idempotent) or that setting timer_running starts a live timer, both of which materially change how an agent should call it.

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 filler or repetition. It is efficient, though the terseness edges toward under-specification rather than disciplined conciseness.

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

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

With a 9-parameter mutation, full schema coverage, an output schema, and annotations, the structured fields cover most of what an agent needs. What is missing is behavioral context the schema cannot express: duplicate-creation risk, what starting a running timer does, and how this differs from update_ticket_time_entry.

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 nine parameters including time_spent's hh:mm pattern, billable's default, and custom_fields keying are documented in the schema itself. The description adds no parameter meaning beyond that, which is the expected baseline when the schema does the work.

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 and resource ('Log time against a ticket'), which is enough to know this creates a time entry rather than reading or editing one. It does not distinguish itself from siblings like update_ticket_time_entry or list_ticket_time_entries, leaving the create-vs-update boundary implicit.

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, no prerequisites, and never mentions the sibling update_ticket_time_entry or timer-related alternatives. The agent must infer from the name alone that this is the creation path.

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 destructiveHint=true and idempotentHint=true, but the description adds the crucial qualifier that the destructive flag is not deletion — the record survives as a requester and can be restored via reactivate_agent. That materially changes how an agent should weigh the call. It omits side effects on existing tickets/assignments.

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 sentence, zero waste, with the state transition and reversibility front-loaded ahead of any procedural detail. Nothing to trim.

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?

An output schema exists so return values need no explanation, and annotations cover the safety profile. The description is sufficient to call the tool correctly, though it leaves open the consequences for the agent's existing tickets and group memberships.

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

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

There is a single parameter (agent_id) with 100% schema coverage, so the schema already carries its meaning. The description adds no format, source, or lookup guidance (e.g., obtainable from get_all_agents / filter_agents), so 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?

States a specific verb+resource ('Deactivate an agent') and immediately clarifies the resulting state ('they become a requester'), which distinguishes it from deactivate_requester in the sibling list. An agent can pick the right tool without opening any 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?

Names the reversal path ('reversible with reactivate_agent'), giving clear context for the counterpart operation, and the 'become a requester' note hints at the alternative deactivate_requester. It stops short of explicit when-to-use/when-not-exclusions or prerequisites (e.g., whether tickets owned by the agent are reassigned).

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 destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is largely given. The description adds the genuinely useful nuance that the action is reversible via reactivate_requester, which counterbalances the alarming destructive flag. It stops short of describing side effects (e.g. effect on assigned tickets), so not a 5.

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 short sentence with zero filler, leading with the action and immediately qualifying reversibility. Nothing could be removed without losing meaning.

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

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

An output schema exists so return values need no explanation, and the one-parameter surface is simple. The description covers effect and reversibility, but omits what deactivation does to related entities (open tickets, group memberships) — a minor gap given the destructive/openWorld hints.

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

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

There is a single required parameter with 100% schema description coverage, so the schema already carries the semantics. The description adds no information about the requester_id beyond what the schema provides; 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?

States a specific verb ('Deactivate') and resource ('a requester'), which cleanly separates it from sibling deactivate_agent and from reactivate_requester. An agent can identify the operation and its target 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 parenthetical names reactivate_requester as the undo path, which gives an agent a recovery route, but there is no explicit guidance on when to deactivate versus update_requester or other requester-mutating siblings. Usage is implied rather than 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?

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: it does not mention irreversibility, cascade effects on group members, or required permissions for a destructive operation.

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

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

It is a single short, front-loaded sentence with no filler. However, its brevity stems from under-specification rather than efficient communication.

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 destructive, open-world mutation with an output schema, the description is insufficient. It says nothing about consequences, whether the deleted group's members or associated data are affected, or what success looks like, leaving the agent to rely entirely on 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 100% with a single required integer parameter 'group_id' documented as 'Agent group ID'. The description adds no meaning beyond the schema, so the 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 'Delete an agent group' is a verbatim restatement of the tool name and title, adding no distinguishing detail. It does not differentiate from sibling destructive tools such as delete_requester_group.

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 whatsoever on when to use this instead of update_group, delete_requester_group, or list/get alternatives. The agent is left to infer everything from the 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 declare destructiveHint=true, idempotentHint=true, openWorldHint=true, and readOnlyHint=false, so the safety profile is fully carried by structured data. The description adds nothing beyond that — it does not say whether members are removed, whether the action is reversible, or what happens to requesters still assigned to the group. No contradiction, but zero added value.

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

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

One short sentence with no filler, so nothing is wasted — but the terseness reflects under-specification rather than disciplined editing. There is no front-loaded context beyond the bare action.

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

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

This is an irreversible destructive operation on a group resource, and the description does not address cascade effects on group members, permission requirements, or failure modes. The presence of an output schema excuses return-value explanation, but not the missing operational 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 coverage is 100% for the single requester_group_id parameter, so the baseline is 3 even though the description adds no parameter meaning. It does not clarify where the ID comes from (e.g. get_all_requester_groups) or what happens with an invalid 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 "Delete a requester group" is a verbatim restatement of the tool name and title, adding no distinguishing detail. It does convey the resource being removed, but offers nothing to separate it from sibling delete operations such as delete_group or delete_requester_group-adjacent 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 when-to-use guidance, no mention of alternatives (e.g. deactivate_requester, remove_requester_from_group), and no prerequisites. An agent must infer entirely from the name that this is the destructive counterpart to update_requester_group.

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 destructiveHint=true and idempotentHint=true, but the description adds the important nuance that this is a soft delete ('move to trash'), which tempers the destructive framing and implies recoverability. It still doesn't say how long trashed articles persist or whether a restore path exists, keeping it below a 5.

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 zero filler; the most important semantic detail (trash, not permanent removal) is the only thing it says.

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 rich annotation set, 100% schema coverage, and an output schema, most of the burden is already carried by structured fields. However, for a destructive operation the description leaves open what trashed means operationally and what the output represents, so it 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?

Schema coverage is 100% and the single parameter carries its own description ('Solution article ID'), so the schema does the work here. The description adds nothing about identifier format or source beyond what the schema already states.

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 and resource ('Move an article to trash'), which is precise enough to distinguish this from a hard-delete sibling and from update_solution_article. It does not name any sibling or note the tool's place in the article lifecycle, so it stops short of a 5.

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

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

There is no guidance on when to use this versus update_solution_article, publish_solution_article, or delete_solution_category/folder, and no prerequisites or exclusions are given. The agent must infer 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 destructiveHint=true and idempotentHint=true, but the description adds useful behavior: the category is soft-deleted to trash and its folders/articles move with it. It does not cover restore paths or permission requirements.

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 zero waste, and the key cascade/trash behavior 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 single-parameter delete tool with an output schema and rich annotations, the description covers the essential behavior (trash + cascade). Minor gaps around restore and permissions keep it from being 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 the single required parameter is documented as "Solution category ID"; the description adds no extra parameter meaning, so the baseline 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 gives a specific action ("Move ... to trash"), the resource (category), and the scope (its folders and articles), which distinguishes it from deleting an individual folder or article.

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 does not state when to use this tool versus get/update/delete siblings, nor does it mention prerequisites or consequences beyond the trash/cascade note.

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 destructiveHint=true and idempotentHint=true, so the description's real contribution is disclosing that the operation is a soft delete ('to trash') and that contained articles are affected – both beyond the annotations. It stops short of saying whether subfolders cascade or whether a restore path 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?

One short sentence, front-loaded with the verb and the key side effect. Nothing is wasted.

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?

An output schema exists and annotations cover the safety profile, so the remaining needs are small. However, for a destructive cascading operation, the description leaves open whether subfolders are also trashed, what permissions are required, and whether recovery is possible.

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

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

Schema coverage is 100% with one parameter, so the schema already fully documents folder_id. The description adds no additional meaning about the identifier's format or origin, which is acceptable given 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?

States a specific verb ('Move ... to trash') and resource ('folder'), and adds useful scope information: its articles are affected too. It does not explicitly differentiate itself from sibling deletion tools like delete_solution_article or delete_solution_category, but the resource is unambiguous.

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

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

No guidance on when to use this versus alternatives such as delete_solution_article, nor any prerequisites or warnings before calling it. The only hint is the word 'trash', leaving the agent to infer the lifecycle from the name alone.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, but the description adds crucial context beyond them: this is a trash operation, not permanent deletion, and can be undone with restore_ticket. That materially changes how an agent should reason about safety.

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 action and immediately followed by the recovery path. No wasted text.

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 one-parameter destructive tool with full schema coverage, annotations, and an output schema, the description provides the essential behavioral nuance: it is reversible. It could mention permission requirements or whether the trash is user-visible, but the core information is 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 the single ticket_id parameter is fully documented in the schema with the #INC-123 / #SR-123 format. The description adds no additional parameter semantics, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Move a ticket to trash') and immediately clarifies reversibility via restore_ticket, distinguishing it from permanent deletion and from the sibling restore tool.

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

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

It clearly indicates this is the soft-delete path and names restore_ticket as the recovery alternative, giving an agent a clear usage context. It does not explicitly state when-not to use it or any prerequisites, so it falls 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?

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is carried structurally. The description adds that the deleted objects are notes and replies specifically, but says nothing about whether deletion is permanent, what permissions are needed, or side effects on the parent ticket.

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, front-loaded sentence with no wasted clauses. It is arguably too terse for a destructive operation, but on the conciseness dimension itself there is nothing to trim.

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?

An output schema and full annotations mean the description need not explain return values or safety flags, and for a one-parameter delete this is close to sufficient. The remaining gap is behavioral: an agent about to destroy a customer-visible reply/note would benefit from knowing whether the action is recoverable and who can perform it.

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

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

Schema coverage is 100% and the single conversation_id field is documented as 'Conversation (reply/note) ID'; the description repeats the same note/reply concept without adding format, lookup, or sourcing guidance. Baseline 3 applies when the schema fully documents the parameter.

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

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

Specific verb (Delete) and resource (a note or reply, i.e. a ticket conversation), and it clarifies that the scope is a conversation rather than the whole ticket, which separates it from delete_ticket. It does not explicitly distinguish itself from update_ticket_conversation, but the destructive verb makes the distinction obvious.

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 indication of when to use this versus update_ticket_conversation or how to recover content afterwards (restore_ticket exists for tickets, but no equivalent is named here). The agent must infer usage entirely from the verb.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is known. The description adds no behavioral context of its own — nothing about irreversibility, what happens to the parent ticket's totals, or re-deletion behavior — so it contributes nothing beyond 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?

A single short sentence that is front-loaded and waste-free, but this is under-specification rather than true conciseness. Nothing in the sentence earns more value than the tool name already conveys.

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 an output schema present, rich annotations, and 100% parameter coverage, the structural gaps are covered elsewhere, so the description need not explain return values. However, for a destructive operation, it says nothing about irreversibility or failure conditions, leaving a meaningful behavioral gap.

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

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

Schema description coverage is 100%, with both ticket_id and time_entry_id documented as integers in the schema, so the baseline of 3 applies. The description adds no meaning beyond the schema, such as the relationship between the two IDs.

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 (delete a time entry on a ticket), which is clear but essentially restates the tool name and title without expanding on scope. It makes no attempt to distinguish this from siblings like update_ticket_time_entry or view_ticket_time_entry beyond the word 'delete'.

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 the sibling time-entry tools (list, view, create, update), nor any stated preconditions such as required permissions or whether the entry must belong to the given ticket. The agent must infer all usage context.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile, so the description correctly spends its words elsewhere. It adds non-obvious behavior: fixed 30-per-page sizing, newest-first ordering with no sort option, and an indexing lag ("changes can take a few minutes to be indexed") that an agent must account for after writes.

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?

Front-loaded with the paging/ordering constraint in the first clause, then a compact field list and operator rule. No filler, and the fresh-indexing caveat is one short sentence that justifies its 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?

For a two-parameter read tool with an output schema and full annotation coverage, everything an agent needs is present: result shape assumptions (30/page, newest first, unsortable), queryable fields, operator behavior, and staleness expectations.

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 baseline is 3, and the description earns an extra point by enumerating the queryable fields and explaining that `~` performs prefix matching on only a specific subset of them. That constraint is not derivable from the schema's single 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 opens with a specific verb+resource ("Search agents") and immediately scopes it with paging and ordering. It never names or contrasts with the obvious siblings get_all_agents / get_agent, so an agent must infer that this is the query-driven variant rather than the list/retrieve one.

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 only implied: the presence of a `query` parameter and the field/operator documentation suggest this is the tool for filtered agent lookups. There is no explicit statement of when to prefer this over get_all_agents, get_agent, or the sibling filter_requesters, and no 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 read-only, idempotent, non-destructive behavior, so the description is free to add operational context — and it does: 30 results per page, newest-first, no sorting possible, and an index-lag warning that changes may take minutes to appear. Those are exactly the traits an agent cannot get from the annotation block or 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 most decision-relevant facts (result cap, ordering, immutability of sort) are front-loaded in the first clause. The field enumeration is dense but functional rather than decorative; only the line-wrapping makes it feel heavier than it is.

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 an output schema present, the description needn't document return shapes, and it correctly focuses on query construction, pagination, and indexing lag. The one gap is that it never says what happens at the 40-page cap or how to reach requesters not yet indexed, though the schema covers the page limit.

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 query examples already live in the schema, so baseline would be 3. The description earns more by enumerating the full set of filterable fields, which the schema only hints at with examples, and by restating which fields support the ~ starts-with operator — information an agent needs to compose a valid query.

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 and resource — "Search requesters" — plus its result ordering and page size, which distinguishes it from get_all_requesters or get_requester. It stops short of naming the sibling it is not, leaving that inference to the agent.

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 by the query-driven framing rather than stated: an agent can infer this is the tool for filtered requester lookup, and that get_all_requesters is the unfiltered alternative. There is no explicit when-to-use / when-not-to-use rule, and no mention that filter_agents covers the agent side of "include_agents".

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/idempotentHint true, so safety is covered. The description adds genuinely non-obvious behavior: a hard 30-result page cap, a 400 response on invalid enum values, case-sensitive snake_case field names, and that the response carries a 'total' match count. That is real operational context beyond the annotations; only paging behavior and sort order are left 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?

Front-loaded with purpose and the page-size caveat, then organized into field list, operator semantics, examples, and error behavior. Dense but every line carries operational value; the example block is the only part that runs long.

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?

An output schema exists and the description still usefully calls out the 'total' field, so return-value explanation is not missing. Combined with the field list, invalid-value behavior, and 512-char limit (in schema), an agent has enough to call this correctly; only pagination-through-many-pages and sorting are 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 coverage is 100%, so the baseline is 3, but the description goes further by enumerating the filterable fields, giving four realistic query examples, noting the :> / :< inclusive semantics, and pointing to get_ticket_fields for custom field API names. This meaningfully reduces bad-query risk beyond what the schema property text 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?

States a specific verb and resource ('Search tickets') and names the mechanism (Freshservice query language) plus the scope limit (30 results per page). It is clearly a query-based search rather than a plain listing, but it never names the sibling tools (get_tickets, get_ticket_by_id) it complements, so differentiation is inferred rather than stated.

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 by the query-language framing and the field list, which tells the agent this is the tool for conditional retrieval. However, there is no explicit 'use this instead of get_tickets when you need filtering' or guidance on paging through more than 30 results, so the agent must infer when this is the right choice.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that the response includes roles and group memberships, which is useful scope information, but says nothing about behavior when the ID does not exist or does not resolve.

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 compact sentence with the verb and key front-loaded and no filler. It is arguably too thin rather than padded, which is the better failure mode for a simple lookup 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 an output schema present and rich annotations, the description need not explain return values, and it correctly notes the payload includes roles and group memberships. It still leaves the agent unable to tell this apart from get_agent_fields or to know the failure behavior for an unknown ID.

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

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

There is a single parameter with 100% schema description coverage, so the baseline is 3. The description only restates 'by ID' and adds no format, range, or lookup-mechanics detail beyond what the 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?

States a specific verb and resource ('Get an agent') and adds the retrieval key ('by ID'), which separates it from the list/filter siblings like get_all_agents and filter_agents. It does not distinguish itself from get_agent_fields, which also reads a single agent.

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 'by ID' implies this is the single-record lookup rather than a browse operation, so usage is inferable. However, no alternatives are named and no condition is stated for choosing this over get_all_agents, filter_agents, or get_agent_fields.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile needs no restating. The description adds only the 'including custom fields' scope note; it says nothing about return shape or whether field metadata (types, options) is included, though an output schema exists to carry 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?

A single short sentence with the scope qualifier attached, no filler and nothing buried. Nothing could be removed without losing 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?

With no parameters, rich annotations and an output schema, the minimum an agent needs is nearly satisfied. What is missing is the workflow context: why an agent would list fields here rather than read them off get_agent, and whether the result is meant to drive create/update payloads.

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 takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies for a no-parameter tool.

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

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

States a specific verb and resource ('List agent fields') and adds the scope detail that custom fields are included. It is clear on its own, but it does not distinguish itself from adjacent field-listing siblings such as get_ticket_fields or list_all_requester_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?

No guidance on when to call this versus get_agent, get_all_agents, or filter_agents, and no mention of the typical use case (discovering field names before create_agent/update_agent). Usage is only inferable 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 declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds one behavioral detail beyond that — that member records come back with the group — but says nothing about behavior for missing/invalid IDs.

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 sentence, front-loaded with the verb and resource, with the one non-obvious fact (members are included) appended. 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?

With an output schema present and annotations covering the safety/idempotency profile, the description only needs to state what the call returns at a coarse level, which it does. Minor gap: it doesn't clarify behavior for nonexistent IDs or how members are represented.

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 single parameter is documented as 'Agent group ID', so the schema carries the load. The description only restates 'by ID' and adds no format or sourcing guidance (e.g., where to obtain a group 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?

States a specific verb and resource ('Get an agent group') plus the lookup key ('by ID') and the response scope ('including its members'). The 'by ID' phrasing implicitly separates it from get_all_agent_groups, but no sibling is named 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?

Usage is only implied: you call this when you have a group_id. There is no explicit when-to-use guidance, no mention of when to prefer get_all_agent_groups, and no prerequisites or error conditions noted.

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, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond the name, such as pagination behavior or how empty results are handled.

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 and is front-loaded, but it is essentially a restatement of the title and omits any useful context. Its brevity comes at the cost of under-specification rather than efficient clarity.

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

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

The tool is simple, with two optional pagination parameters, full schema descriptions, an output schema, and rich annotations. For that complexity level the description is minimally adequate, though it still leaves sibling selection and list behavior 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%, with both page and per_page documented in the input schema. The description adds no parameter 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 clear verb ('List') and resource ('agent groups'), so the agent knows this is a read operation returning multiple agent groups. It does not explicitly distinguish itself from nearby siblings such as get_agent_group or get_all_agents, 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 description gives no when-to-use guidance, no exclusions, and does not mention alternatives like get_agent_group for a single group or get_all_agents for agents. Usage is only implied by 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered by structured data. The description adds nothing beyond that — no mention of default page size, max 100 per page, or result ordering — so it contributes no behavioral context of its own.

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 with zero waste, but this is under-specification rather than conciseness — nothing is front-loaded because nothing is stated. An agent learns nothing it could not infer from the tool name alone.

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 output schema and full schema coverage relieve some burden, but for a five-parameter listing tool that competes with 'filter_agents', the description should at minimum say whether it returns all agents unfiltered and how pagination behaves. That routing information is entirely absent.

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 page, email, state, active and per_page are all documented in the schema, including the enum-like agent type and the max-100 page size. The description adds nothing on top, so the 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?

"List agents" merely restates the tool name and title with no additional specificity. It gives no hint of scope, filtering capability, or pagination, and it does nothing to distinguish the tool from sibling 'filter_agents' or 'get_agent'.

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 when-to-use guidance and no mention of the obvious alternative 'filter_agents', which also returns agents. With two agent-listing siblings present, the absence of routing guidance is a real ambiguity rather than a neutral omission.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds nothing about pagination semantics, ordering, completeness of results, or what a page returns — all relevant for a paginated list call.

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 waste, but it is under-specified rather than concise — it spends its single sentence repeating the title instead of supplying any disambiguating 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?

An output schema exists, so return values needn't be explained, but the description still omits scope (all groups vs. a filtered subset), how pagination should be driven, and how this differs from the several other group-listing tools in the sibling set.

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

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

Schema coverage is 100% with only two optional pagination parameters that are fully documented (page starting at 1, per_page max 100). The description adds no meaning beyond the schema, but with complete schema documentation 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 is a near-verbatim restatement of the tool name and title ("List requester groups"), adding no scope, filter, or resource detail. It doesn't distinguish this from siblings like get_requester_group, get_all_agent_groups, or list_requester_group_members.

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 indication of when to call this versus get_requester_group (single group) or list_requester_group_members. The agent must infer usage purely from the name and the fact that it takes no required parameters.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds nothing on top: it says nothing about pagination behavior, the default exclusion of agents (include_agents defaults to false, a real behavioral trait), or result ordering, so it earns no credit beyond the structured fields.

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 filler, and the core action comes first. It is arguably too terse for a 7-parameter list tool, but nothing in it is wasteful.

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 7-parameter listing tool with pagination and a default that hides agents, the description leaves the agent to discover key behavior from the schema alone and gives no routing signal against filter_requesters. Output schema and annotations cover the return shape and safety, but the selection-time context is thin.

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 parameter including page, per_page, active and include_agents is already documented in the schema. The description only restates the email/phone lookup idea and adds no format or precedence semantics (e.g. how multiple filters combine). 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?

States a specific verb and resource ("List requesters") plus the optional lookup keys, so the action is unambiguous. However, it never distinguishes this tool from the sibling filter_requesters, which reads as the same job, nor from get_requester for single-record retrieval.

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?

"Optionally looked up by email or phone" implies when the filter parameters are worth setting, but there is no explicit guidance on when to prefer this over filter_requesters, nor any statement about when not to use it. Usage is only inferable.

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, idempotentHint=true and destructiveHint=false, so the safety profile is fully carried by structured fields. The description adds nothing beyond that — no note that results are paginated, whether the list is workspace-scoped, or what happens when workspace_id is 0 (that detail lives only in 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?

A single six-word sentence with zero waste and the resource stated immediately, so structure is fine. But the brevity reads as under-specification rather than disciplined concision — there is room for one more sentence of routing or scoping guidance that would earn 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?

An output schema exists and the input schema is fully described, so an agent can call this correctly without further text. What is missing is only the connective context an agent would want when choosing between this and the other solution-listing tools.

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 page, per_page and workspace_id all documented including defaults and the max-100 cap, so the schema does the heavy lifting. The description adds no parameter meaning of its own, which is the baseline expectation when a schema is this complete.

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?

Specific verb+resource ("List ... categories") scoped to the knowledge base, which maps onto Freshservice's solution module and implicitly separates it from the folder/article siblings. It does not, however, explicitly distinguish itself from get_solution_category or explain that it returns categories only, so the differentiation is inferred rather than stated.

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, no mention of when to prefer get_solution_category for a single lookup, and no prerequisites or context about what the listing is for. The agent must infer everything from the tool name and 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that — it discloses that the response is a truncated snippet rather than the body, which prevents an agent from assuming it got full content. Pagination and the 'trash' filter behavior are left to 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?

Two short sentences, zero filler, with the output-shape constraint front-loaded and the follow-up tool pointer second. Nothing could be cut without losing routing 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?

With an output schema present, annotations covering safety, and full parameter documentation, the description carries only what it must: what comes back and how to get the full version. The only gap is not naming search_solution_articles for the case where the folder is not yet known.

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 including include_body already carries its own guidance and token-size warning. The description reinforces the snippet-vs-body distinction but adds no syntax or format detail beyond what the schema provides, so 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?

States a specific verb and resource (list articles in a folder) and pins down the payload shape: metadata plus a short plain-text snippet, not the full body. That scope statement alone separates it from get_solution_article and from search_solution_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?

Explicitly routes the agent to get_solution_article when a full article body is needed, which is the main confusion risk for this tool. It does not mention search_solution_articles as an alternative when the folder is unknown, so one meaningful exclusion is missing.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds essentially nothing beyond that: it doesn't mention pagination behaviour, the trash filter, or completeness/ordering of results — all of which are behaviours an agent would want described.

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 short sentence, front-loaded and free of filler. It is efficient, though the terseness is partly the cause of the gaps elsewhere rather than a virtue in itself.

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 an output schema and fully documented parameters, the definition is callable without ambiguity, and a 3 reflects that minimum-viable adequacy. The remaining gap is navigational: nothing distinguishes this from list_solution_subfolders or explains what a solution folder is in this product.

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 page, per_page, filter ('trash') and category_id all documented inline. The description's 'in a category' merely echoes category_id, so the baseline of 3 for a fully documented schema is warranted.

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 gives a verb ('List') and a resource ('the folders in a category'), so the basic operation is clear. However, it never says these are 'solution folders' or relates them to the neighbouring list_solution_subfolders / get_solution_folder / get_list_of_solution_article tools, leaving the agent to infer scope from the tool name alone.

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 versus list_solution_subfolders, get_solution_folder, or list_solution_service_categories. The only implicit hint is that a category_id is required, which the schema already states.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered without the description. The description adds only the scoping insight that results are per-ticket; it says nothing about ordering, empty-result behavior, or whether non-SR tickets return an error.

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 sentence with no filler, and the resource plus its scope are front-loaded. It could be tightened slightly for a more scannable structure, but nothing in it is wasted.

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 one-parameter, read-only list tool with an output schema and complete annotations, the description covers what to fetch and from where. The only meaningful gap is the absence of guidance on behavior for tickets with no requested items or non-service-request tickets.

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 single ticket_id parameter is documented with a helpful format note (#INC-123 / #SR-123). The description adds no further constraint on the parameter, so the 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?

States a specific verb ('List') and a specific resource ('service catalog items requested on a service-request ticket'). The ticket-scoping clause distinguishes it from the catalog-listing siblings like list_service_items and search_service_items, though it never names those alternatives 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?

The phrase 'on a service-request ticket' implies this is the follow-up to fetch items attached to an existing SR, which is useful implied context. But there is no explicit when-to-use guidance, no stated prerequisite (e.g. that the ticket must be a service request), and no named alternative for listing the catalog itself.

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 readOnly, idempotent, non-destructive, and openWorld, so the safety profile is covered, but the description adds nothing beyond them — no error behavior for an unknown ID, no access/permission context, nothing about what an openWorld lookup implies. With the bar lowered by annotations, a 2 reflects a description that contributes no additional behavioral context at all.

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, front-loaded sentence with zero padding. It is concise to a fault — the size is appropriate but the space saved isn't spent on any routing or behavioral 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?

An output schema exists so return values needn't be explained, and the single required parameter is fully documented, making the definition minimally sufficient. However, in a namespace with near-duplicate requester retrieval tools, the description omits the discrimination an agent needs to select 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?

Single integer parameter with 100% schema description coverage, so the schema fully documents it and the baseline is 3. The description only restates that the ID is the lookup key and adds no format, source, or scope detail 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?

States a specific verb and resource ('Get a requester') plus the lookup key ('by ID'), which distinguishes a single-record fetch from the sibling list tools get_all_requesters and filter_requesters. It doesn't explicitly name those siblings, so differentiation is implicit rather than stated.

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 versus get_all_requesters, filter_requesters, or get_agent. The agent must infer the choice from the tool name alone; there are no 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, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered without the description. The description adds no behavioral context beyond annotations – no notes on not-found handling, whether members are included, or sensitivity of the data. With annotations carrying the load, 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?

One short, front-loaded sentence with no wasted words. It is efficient, though borderline under-specified rather than deliberately concise.

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?

An output schema exists and annotations are rich, so the description does not need to explain return values or safety. However, for a lookup tool surrounded by group-management siblings, it leaves ambiguity about whether membership or only group metadata is returned, and it offers no routing to related tools.

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 single parameter is documented in the schema, so the baseline of 3 applies. The description mentions 'by ID' but adds no format, type, or validation detail beyond what the 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?

States a specific verb and resource ('Get a requester group') plus the lookup key ('by ID'), which distinguishes it from the list-style sibling get_all_requester_groups. It does not explicitly name the sibling or clarify what a 'requester group' returns, but the purpose is immediately 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 'by ID' phrasing implies this is the single-record lookup versus get_all_requester_groups, but no explicit when-to-use guidance or prerequisites are given. There is no mention of alternatives such as list_requester_group_members when the caller actually needs membership data.

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, idempotentHint=true, and destructiveHint=false, so the safety profile needs no repetition. The description adds value the annotations cannot convey: the response includes custom field names intended for use in a subsequent request, which tells the agent this call is a lookup step and explains the key payload content. It stops short of noting what happens when display_id is invalid.

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, front-loaded with the action and resource, with the one piece of non-obvious payload information appended. Nothing is wasted and nothing needs to be re-read.

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?

An output schema exists, so return values need no explanation, and the read-only annotations cover the safety posture. The description still provides the practical reason to call this tool, which is enough for a 1-parameter lookup. The only gap is the absence of guidance on routing between this tool and the service-item search and list 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?

Schema coverage is 100% with a single required parameter, and the schema already documents display_id as "Service item display_id." The description adds no format, range, or sourcing guidance for that identifier, so the baseline 3 is correct when the schema carries the parameter documentation.

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

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

States a specific verb and resource ("Get a service item") and adds what the payload contains: form fields and custom_fields names. That is more than a restatement of the title. However, it doesn't explicitly distinguish itself from the sibling retrieval tools list_service_items, search_service_items, or get_requested_items.

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 only implied by the parenthetical "custom_fields names to use when placing a request," which hints at the workflow (look up item before calling create_service_request). There is no explicit statement of when to use this tool versus list_service_items or search_service_items, and no prerequisites or failure conditions 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 declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description still adds useful behavioral detail by disclosing the two content representations returned in the response, which is more than the annotations provide. It says nothing about not-found behavior or article state (draft vs published), keeping it off a 5.

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 zero filler; the core action and return shape are front-loaded and the ID-sourcing hint follows. Nothing could be removed without losing 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?

With an output schema present, annotations covering the safety profile, and a single fully described parameter, the description supplies everything needed to call the tool correctly. Only edge cases such as a missing or unpublished article ID go unmentioned.

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 single parameter is already documented as 'Solution article ID', so the baseline is 3. The description goes slightly beyond the schema by naming the two sibling tools that produce valid IDs, which concretely helps the agent source the value.

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

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

Names a specific verb and resource ('Read a knowledge-base article by ID') and even specifies what the payload contains: full HTML in 'description', plain text in 'description_text'. It implicitly separates itself from the list/search siblings by noting the ID comes from them, so an agent can tell this is the single-article fetch rather than a listing call.

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

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

Explicitly states where to obtain the required argument ('Use the id from search_solution_articles or get_list_of_solution_article'), which is a clear usage context with named alternatives. It does not state when not to use it (e.g., that it does not list or search), so it falls short of a full when/when-not treatment.

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, idempotentHint, openWorldHint, and destructiveHint=false. The description adds no behavioral detail beyond them, such as auth needs, not-found behavior, or rate limits, so it contributes little on this dimension.

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 is appropriately sized for a simple one-parameter getter.

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 one-parameter read-only getter with rich annotations and an output schema, the description covers the core action adequately. It is slightly incomplete on usage alternatives and not-found behavior, but annotations and the output schema fill most 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 coverage is 100% and the single category_id parameter is already documented as 'Solution category ID'. The description only restates 'by ID' and adds no format or semantic detail beyond the schema, matching the baseline 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?

States a specific verb ('Get'), resource ('knowledge-base category'), and selector ('by ID'), which distinguishes it from list/get_all and mutation siblings. It does not explicitly name the sibling alternative, so it falls short of full 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?

Usage is implied: call it when you know the category ID and need one category. There is no explicit when-to-use, when-not, or alternative routing such as using get_all_solution_category for listing, leaving clear gaps.

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, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds nothing beyond them — it doesn't say whether subfolders or articles are included in the result, what happens for a nonexistent ID, or anything about visibility/permission scoping on an open-world knowledge-base 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, front-loaded sentence with no filler. Its brevity is a completeness problem rather than a conciseness one, so it scores well here but not perfectly.

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?

An output schema exists, so return structure need not be described, and there is only one fully documented parameter. Still, for a lookup tool inside a folder/category/article hierarchy, the description leaves the terminology mismatch and the folder's scope (subfolders/articles included or not) unresolved.

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 single parameter folder_id is documented as 'Solution folder ID'. The description adds no extra meaning, such as how to obtain a valid folder_id (e.g., from get_list_of_solution_folder); baseline 3 applies when the schema does the work.

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') and resource ('folder by ID'), so the operation is unambiguous. However it does not differentiate from near siblings such as get_solution_category, get_list_of_solution_folder, or list_solution_subfolders, and it swaps terminology ('knowledge-base folder' vs. 'solution folder'), which leaves a small doubt about whether it is the same object hierarchy.

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 condition for when to call this versus the list/lookup siblings, and no prerequisites. An agent must infer that get_list_of_solution_folder enumerates folders while this one retrieves a single known folder_id.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive semantics, so the safety profile is covered. The description's additional value is limited to listing returned fields, which largely duplicates the existing output schema, and it says nothing about not-found/permission behavior or how the `include` option changes the response payload.

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, purpose front-loaded before the return payload, with no filler. The second sentence's field enumeration partially restates what the output schema already declares, a minor 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?

With an output schema, rich annotations and full parameter coverage, the description only needs to establish purpose and it does. Minor gaps: what happens when the ticket ID does not exist, and any permission constraints, are unstated.

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%, including the enum of includable relations and the caveat that conversations returns at most 10. The description adds no parameter meaning beyond that, so the 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?

"Get a ticket by ID" states a specific verb and resource, and the ID-based lookup implicitly separates this from bulk siblings like get_tickets and filter_tickets. It does not name an alternative tool explicitly, so it falls short of the 5-level bar for 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?

The trigger condition (you already have a ticket ID) is implied by the tool name and the required ticket_id parameter, but the description never says when to prefer get_tickets/filter_tickets for searching, nor what to do if the ID is unknown. Usage is inferable rather than 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so safety and idempotency are covered. The description usefully adds that custom fields and their allowed choices are included, but says nothing about pagination, field-type coverage, or freshness of the schema 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?

One compact sentence with the resource front-loaded and no filler. It is efficient but so short that it leaves obvious questions (scope, workspace behavior) unaddressed.

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 rich annotations, a fully documented single parameter, and an output schema, the definition is minimally sufficient. It still omits whether the returned field set is workspace-filtered and whether choices reflect dependent/cascading fields, which an agent calling this before create_ticket would want to know.

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

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

There is a single parameter with 100% schema description coverage, including the FRESHSERVICE_WORKSPACE_ID default and the '0 means all workspaces' semantics. The description adds nothing about workspace scoping, so 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?

Specific verb ('List') plus resource ('ticket form fields') and it enumerates what is returned (custom fields, API names, allowed choices). It is clearly distinguishable from get_tickets or create_ticket, though it does not name the near-sibling get_agent_fields to differentiate scope.

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

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

No explicit when-to-use or when-not-to-use statement, and no mention of alternatives such as get_agent_fields or list_all_requester_fields. Usage is only implied by the fact that API names and allowed choices are needed before building ticket payloads.

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 the tool is read-only, idempotent, open-world, and non-destructive. The description adds useful behavioral context: results are newest first and default to a 30-day window unless filter or updated_since is provided. It does not discuss pagination or rate limits, but those are secondary 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 two short sentences with no waste. The default scoping rule is front-loaded, and the alternative-tool guidance follows 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?

Given rich annotations, 100% schema description coverage, and an output schema, the description provides the essential selection and scoping information an agent needs. It does not need to repeat return-value or parameter details already covered structurally.

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 parameter meanings are already well documented. The description adds the interaction between filter and updated_since in determining the 30-day default window, but does not provide additional detail on page, include, workspace_id, or the filter enum values.

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

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

The description states a specific verb and resource ('List tickets') and adds important scope ('newest first'). It explicitly distinguishes the tool from the sibling filter_tickets, so an agent can choose between them without opening either 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?

It clearly states the default behavior when no filter or updated_since is supplied and explicitly routes arbitrary-condition queries to filter_tickets. This gives both when-to-use and when-to-use-an-alternative guidance.

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