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

Annotations only supply openWorldHint, so the description carries the burden and does a good job: it discloses idempotent skipping of already-attached files, that the API rejects calls adding nothing, and that closed/invalid tickets are locked. It omits permission/auth requirements beyond the token and any indication of what the call returns.

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

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

Three tightly packed sentences with zero filler; the core action leads and the constraints follow in order of relevance. Every sentence carries a distinct, actionable fact.

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

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

For a 3-parameter mutation tool with no output schema and thin annotations, the description covers the important failure modes and locking behavior. It could still say more about required edit permissions or what happens on partial success.

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 note that fileIds come from upload_attachment, so the schema already documents all three parameters. The description's 'by their file ids' adds no syntax or format detail beyond it, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Link already uploaded files to a ticket by their file ids') and the phrase 'already uploaded' implicitly separates it from upload_attachment. It never names the sibling outright, so the routing distinction relies on inference.

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?

Preconditions are explicit: files must already exist (implying upload_attachment first), no-op calls are rejected, and closed/invalid tickets reject edits. It gives clear when-not conditions but never states the positive trigger or names the alternative tool directly.

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 idempotency and open-world behavior. The description adds useful context beyond that by stating the visible effect of approval and the API-key requirement, though it does not discuss permissions, error cases, or moderation side effects.

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

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

The description is two short sentences with the core action and effect front-loaded, followed by the authentication prerequisite. There is no wasted language.

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

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

For a simple one-parameter approval tool with annotations covering idempotency and open-world behavior, the description gives the essential action, effect, and auth requirement. It could mention expected response behavior, but no output schema exists and the remaining gap is minor.

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 commentId parameter is fully documented in the schema. The description does not add syntax or meaning beyond identifying that a comment is being approved, 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 names a specific verb and resource: approve a moderated comment. It also states the concrete effect, making the comment publicly visible, so it is distinguishable from generic comment mutations such as update_comment or delete_comment.

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

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

It implies the appropriate use case by saying the comment is moderated and approval makes it public, and it adds the API-key prerequisite. However, it does not explicitly compare this tool with alternatives such as update_comment or approve_ticket, nor does it state when not to use it.

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

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

Annotations cover idempotency (idempotentHint=true) and open-world behavior, so the description is not the only source. It still adds real value by disclosing the postcondition (ticket becomes visible and editable) and the auth requirement (API key), though it doesn't say whether approval can be undone or who is permitted to approve.

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, no redundancy, with the effect of the operation front-loaded before the access requirement.

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 approve operation with no output schema, the description covers the action, its consequence, and the auth prerequisite. It leaves minor gaps around reversibility and permission scope, but nothing required to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single required parameter ticketId is fully documented in the schema. The description adds no syntax or format detail 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?

States a specific verb (approve) and resource (moderated ticket) plus the resulting state change, which clearly separates it from approve_comment and set_ticket_state. It does not explicitly name a sibling alternative, so it stops just short of the top mark.

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 'moderated ticket' implies the precondition for use, but there is no explicit when-to-use guidance, no statement of when approval is inappropriate, and no pointer to related tools such as set_ticket_state or approve_comment.

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 only carry openWorldHint, so the description does the heavy lifting and delivers real behavioral detail: duplicate handles are rejected with 409, private projects get an API-generated access token returned in the response, and an API key is required. It does not describe the response shape for non-private projects or rate limits, 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?

Four short sentences, front-loaded with the core action and then layering constraint, side effect, and precondition. Each sentence carries information, with only mild redundancy between the description's handle note and the schema's identical wording.

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

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

With no output schema, the description usefully covers the error case (409), the conditional side effect (access token), and the auth requirement. It is close to complete, missing only what the success response contains for non-private projects and whether the new project is returned at all.

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

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

Schema description coverage is 100%, so the schema already documents name, handle, and isPrivate fully. The description restates the uniqueness of handle and the private-token consequence of isPrivate, reinforcing rather than adding new semantics, which matches 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 and resource ("Create a support project") that clearly separates it from list_projects, get_project, update_project, and delete_project by verb alone. It does not, however, explicitly name or contrast with any sibling, 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?

Usage is implied: the uniqueness/409 rule signals this is only for genuinely new projects, and the API-key note sets a precondition. But there is no explicit when-to-use statement, no mention of update_project as the alternative for existing projects, 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 only carry openWorldHint, so the description carries most of the burden, and it delivers the highest-value disclosure available: the API returns a status envelope rather than the new ticket, forcing a follow-up list_tickets call to get the id. It also surfaces the attachment upload prerequisite, which is behavioral rather than structural.

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

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

Three dense sentences, zero filler, with the creation scope front-loaded and the workflow (upload first, list afterward) laid out in call order. Every sentence earns its place.

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

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

For a 9-parameter mutation tool with no output schema and minimal annotations, the description covers the essentials an agent needs: identity resolution, auth-relevant context is delegated to a fully documented schema, the attachment prerequisite, and the surprising return shape. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents each field. The description still adds non-schema semantics: projectId/projectHandle as interchangeable identifiers and the ordering constraint that attachmentFileIds must come from a prior upload_attachment call.

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 ("Create a new ticket in a project") with the identification mechanism named (projectId or projectHandle). An agent can immediately distinguish this from update_ticket, delete_ticket, and the comment/attachment siblings without opening a 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?

Gives a clear pre/post workflow: attachments must be uploaded via upload_attachment first and passed as attachmentFileIds, and list_tickets must be called afterward to obtain the id. It names the sibling tools and the ordering conditions, though it does not state when NOT to use this tool (e.g. vs. create_project or add_ticket_attachments).

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?

Goes well beyond the destructiveHint/idempotentHint annotations by disclosing what actually gets destroyed (the ticket-file link is gone permanently) versus what survives (the file remains in the site's file manager), plus the confirm gate and the locked-state rejection rule. This is the kind of nuance annotations cannot express.

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

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

Three sentences, each carrying distinct load: what it does, the irreversibility nuance, and the prerequisites/preconditions. The destructive consequence is front-loaded rather than buried.

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, no-output-schema tool this is complete: irreversibility, the confirm requirement, the preserved-file nuance, and the locked-state failure mode are all covered. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so each parameter is already documented in the schema, including confirm's const:true and the token/fileId/ticketId meanings. The description reinforces the confirm requirement but adds no new syntax or format detail beyond the schema; 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 ('Remove a file from a ticket') and implicitly distinguishes itself from the sibling attach/download/list tools. An agent can identify exactly what this does 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?

Gives a clear precondition (confirm must be set to true) and a negative case (closed or invalid tickets are locked and reject edits). It does not name an alternative tool for related operations, but the when/when-not conditions are explicit.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value beyond them by spelling out irreversibility ('cannot be undone, the text is gone afterwards'), the consequence (comment text destroyed), and the confirm gate.

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

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

Three short sentences, front-loaded with the action and its consequence. Slightly redundant, since 'Permanently' and 'cannot be undone' convey overlapping meaning, but it is otherwise efficient with no waste.

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

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

For a simple three-parameter deletion tool with no output schema, the description covers the action, irreversibility, and the confirm prerequisite, and annotations cover the safety hints. Nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so ticketId, commentId, and confirm are fully documented in the schema, and the description only restates the confirm requirement. Per the baseline for high coverage, a 3 is appropriate since the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('Permanently delete a comment from a ticket'), which is clear and unambiguous. It does not explicitly distinguish itself from siblings like update_comment or delete_ticket, 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 supplies a prerequisite ('Requires confirm set to true'), which is useful usage context, but gives no guidance on when to choose this tool over alternatives such as update_comment or delete_ticket. 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 and idempotentHint, and the description adds substantial context beyond them: the exact cascade of destroyed entities, that the action cannot be undone, and the authentication/confirmation requirements. No contradiction with the declared hints.

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 tight sentences, zero waste. The destructive scope is front-loaded, followed by irreversibility and prerequisites in decreasing order of importance.

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 2-parameter destructive mutation with no output schema, the description covers scope of destruction, reversibility, auth and confirmation, which is everything an agent needs to call it safely.

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

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

Schema coverage is 100%, so both parameters (projectId, confirm) are already documented in the schema, including the const: true constraint. The description reinforces confirm=true but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (delete) and resource (project) and immediately scopes the blast radius to every ticket, comment and attachment link. This clearly distinguishes it from siblings like delete_ticket, delete_comment and delete_attachment.

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?

Gives a strong use-context signal ('most destructive call of the whole API') and states the prerequisites (API key, confirm=true), which tells the agent when this tool is appropriate. It does not explicitly name alternative tools or spell out when-not-to-use beyond the irreversibility warning.

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, but the description goes well beyond them by disclosing the cascade to comments and attachment links, the total absence of trash/restore, and the API-key plus confirm=true precondition. These are exactly the consequences an agent needs before committing an irreversible action.

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

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

Three sentences, each load-bearing: what is destroyed, that it is irreversible, and the safer alternative. The destructive consequence is front-loaded, and there is no padding.

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 destructive delete with no output schema, the definition covers the whole decision surface: scope of deletion, irreversibility, auth requirement, confirmation flag, and a preferred alternative. Nothing an agent needs in order to call this safely is missing.

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

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

Schema description coverage is 100% and both parameters (ticketId, confirm) are already documented in the schema, so the baseline is 3. The description reinforces the confirm semantics ('confirm set to true') but adds no format or edge-case 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 ('Permanently delete a ticket') and immediately scopes the blast radius ('together with all its comments and attachment links'). It also names the sibling alternative, so an agent can distinguish it from set_ticket_state 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?

Explicitly gives the when-not condition: 'Prefer set_ticket_state with "closed" or "invalid" unless the record really has to disappear.' This is a direct routing rule with a named alternative and the deciding criterion.

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 cover the safety profile (readOnlyHint=true, openWorldHint=true), and the description adds genuinely useful context beyond them: the conditional local-write behavior and the fact that the return value differs depending on outputPath. It does not, however, discuss auth/token implications or failure modes when the path is unwritable, which keeps it from 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 tightly written sentences, zero filler, with the primary action (resolve the URL) front-loaded and the conditional branch second. Every clause carries information an agent needs.

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

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

There is no output schema, and the description compensates by stating exactly what is returned in each mode (URL only vs. saved file path). Combined with the 100%-covered input schema, an agent has everything needed to call this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning on top of the schema by explaining the semantic effect of supplying outputPath (file written) versus omitting it (URL only). The overwrite detail is already carried by the schema, so it is not a full 5.

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 verb+resource (resolve the download URL of a ticket attachment) and even spells out its dual-mode behavior (URL only vs. saved file). It is unambiguous what the tool does, but it never differentiates itself from siblings such as list_ticket_attachments, upload_attachment, or delete_attachment, 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?

Usage is only implied via the outputPath conditional ("when outputPath is given... Without outputPath only the URL is returned"). There is no statement of when to choose this tool over list_ticket_attachments for discovery or how it relates to the upload/delete attachment siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and reach are covered by structured data. The description adds only the key-based lookup nature; it says nothing about authorization behavior, rate limits, or what a failed lookup returns.

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; every word (verb, resource, scope, lookup key) carries information.

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

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

For a simple read-one tool with full annotation coverage, a complete schema, and no output schema, this is nearly sufficient. The only shortfall is that it does not spell out the relationship to list_projects or update_project, leaving the agent to infer the boundary.

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 a clear explanation of when the optional 'token' is needed, so the schema does the heavy lifting. The description's 'numeric id' merely restates the projectId field and adds no format, range, or token-usage 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 ('Read'), resource ('project'), and cardinality ('single') with the lookup key ('numeric id'). This implicitly separates it from list_projects and the create/update/delete_project siblings, though it never names them.

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

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

The phrase 'a single project by its numeric id' implies the fetching-one-by-key use case and thereby rules out browsing, but there is no explicit when-to-use statement, no mentioned alternative (e.g. list_projects for discovery), and no prerequisites called out.

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, but the description adds genuinely new context: the exact fields returned and, importantly, that the API key itself is never returned. That security-relevant disclosure is beyond what the annotations or empty schema convey.

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 tightly packed sentences with zero filler, front-loaded on the core action with the return payload enumerated immediately after. Every clause earns its place.

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

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

With no output schema, the description carries the burden of describing returns and does so by naming the exact fields. It is nearly complete for a simple read-only introspection tool; only the response shape/format is left unstated, which is minor here.

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 per the baseline there is nothing for the description to disambiguate; the schema is trivially complete at 100% coverage. A 4 is appropriate with no parameter meaning to add.

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 ('Show how this server is configured') and then enumerates exactly what is surfaced: API base URL, key presence, and accepted ticket states/types/priorities. It is unmistakably distinct from the ticket- and project-oriented siblings.

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

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

Usage is implied rather than stated – an agent can infer this is a diagnostic/introspection call with no alternatives, but the description never says when to reach for it (e.g., before configuring or troubleshooting). No explicit when/when-not guidance is provided.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: comments are returned unless switched off, attachments always come along, and everything arrives in one call rather than requiring separate lookups.

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

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

Two sentences with zero filler: the first defines the payload, the second gives the trigger condition. The most actionable guidance (when to call) is front-loaded after the payload summary and nothing is repeated.

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

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

With no output schema, the description usefully names what is returned (ticket, attachments, comments) and the default behavior for comments. It leaves return format, pagination, and error cases unstated, but for a simple single-resource read that is a minor 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 coverage is 100%, so ticketId, token, and includeComments are already fully documented in the schema. The description's mention of comments being included 'unless switched off' broadly maps to includeComments but adds no extra syntax or semantics. Baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb (Read) and resource (a single ticket) and enumerates what comes back (attachments and comments). The word 'single' cleanly separates it from the sibling list_tickets, and the comment inclusion distinguishes it from list_ticket_comments.

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 tells the agent when to call it: before replying (reply_to_ticket) or changing state (set_ticket_state), which is exactly the sequencing an agent needs. It stops short of stating when NOT to use it or naming alternatives for bulk retrieval, so it is clear context without exclusions.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds meaningful disclosure beyond that: with an API key, private projects and their access tokens are exposed, which is a data-sensitivity fact an agent should know before calling.

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 filler, with the core action front-loaded and the API-key conditional following immediately. Every clause earns its place.

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

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

For a no-required-parameter list tool with no output schema, the description covers the meaningful variance in return content (public vs private, token inclusion). It stops short of describing pagination or result ordering, but nothing essential to invoking it correctly is missing.

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

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

Schema description coverage is 100% and the single token parameter is fully documented in the schema, so baseline is 3. The description restates the token's matching behavior but adds no syntax, format, or precedence detail beyond what the schema already says.

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 the support projects') and its scope differs clearly from the singular get_project sibling. It does not explicitly name the alternative, so differentiation is implied 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 conditional context for what is returned depending on whether an API key is present, which implicitly tells the agent when the token parameter matters. However, it never states when to choose this tool over get_project or other listing siblings, leaving usage largely 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=true and openWorldHint=true, so the safety profile is covered. The description adds value by disclosing the returned fields (file id, file name, public URL), which matters because there is no output schema. It stops short of mentioning ordering, pagination, or auth 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 filler: verb, resource, and return payload in one pass.

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

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

With no output schema, the description usefully enumerates the returned fields, and annotations carry the safety profile. Only minor gaps remain around result ordering and whether the list can be large/paginated.

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 both parameters (token, ticketId) are already documented in the schema. The description adds no syntax or format meaning beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb ('List') and resource ('files attached to a ticket') plus the returned fields. It is clearly distinguishable from write siblings like add_ticket_attachments or delete_attachment, 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 description gives no guidance on when to use this versus the neighboring attachment tools (add_ticket_attachments, download_attachment, delete_attachment). Usage is only implied by the verb-resource pairing, and no prerequisites or exclusions are 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 establish readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavioral detail beyond them: deterministic ordering (oldest first, as the API returns them) and conditional visibility of unapproved comments depending on API key presence.

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 compact sentences with zero waste; the ordering guarantee is front-loaded and the API-key visibility note follows. Nothing repeats the name or 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?

For a read-only list tool with no output schema, the ordering and visibility behavior are covered well. Pagination or result-size limits are not addressed, which is the main remaining gap an agent might care about when consuming a list response.

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 both token and ticketId are already documented in the schema, and the description adds no additional semantics for either parameter. Baseline 3 applies when the schema carries the parameter burden.

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

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

States a specific verb and resource ('List the comments of a ticket') and is clearly distinct from siblings like list_tickets, list_ticket_attachments, and update_comment. It does not, however, explicitly contrast itself with any sibling, so an agent must infer the boundary from the resource noun 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?

Usage context is implied rather than stated: the note that an API key causes unapproved comments to be included is a useful prerequisite hint, but there is no explicit when-to-use/when-not guidance and no pointer to alternatives such as get_ticket for ticket-level 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?

Discloses a non-obvious implementation trait beyond the annotations: only projectId is filtered server-side while every other filter is applied client-side by this server on the returned list, which has real performance/latency implications. It also discloses the default return shape (compact summary) and how to widen it via format='full'.

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?

Four sentences, front-loaded with the core action, followed by the behavioral caveat, return-format note, and positioning. Every sentence carries distinct information with no repetition.

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

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

For a 16-param tool with no output schema, the description usefully compensates by describing the return format and default. It does not touch pagination behavior (limit/offset interaction) or default sort, though those are covered in 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 coverage is 100%, so parameters are self-documenting and the baseline is 3. The description goes further by clarifying which filters are truly API-backed versus server-side and by explaining what format='full' actually returns (complete records including attachments), adding meaning beyond the schema.

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

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

States a specific verb and resource ('List tickets') and enumerates the filter dimensions. It is clearly distinguishable from get_ticket (single record) and list_ticket_comments, and it names its role as 'the default way to find a ticket id'.

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

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

Explicitly positions itself as the default entry point for locating a ticket id, which routes agents away from other tools when browsing. It does not, however, state when to prefer get_ticket or how it relates to set_ticket_state/update_ticket.

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 only carry openWorldHint=true, so the description bears the full behavioral burden and delivers: it discloses the notification-email side effect, the unauthenticated email requirement, and that moderation may withhold the comment pending approval. These are exactly the non-obvious traits an agent cannot get from the schema or 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?

Four short sentences, front-loaded with the action and the primary-use statement, with no filler. The auth sentence partially duplicates the schema's email description, which is the only small 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 no output schema and minimal annotations, the description adequately covers auth paths, side effects, and moderation gating for a create-comment tool. It does not say what is returned (comment id) or how failures surface, which leaves a modest 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%, so all four parameters are already documented (email 'required for unauthenticated calls', token for private projects). The description restates the email/auth condition with added moderation context but says nothing about token or the comment/ticketId fields, 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?

States a specific verb and resource ('Post a reply as a comment on a ticket') and frames the role as the primary answer path. It does not name or contrast with nearby siblings such as update_comment or approve_comment, so an agent still has to infer the boundary from the sibling list.

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?

'This is the normal way to answer a ticket' gives an explicit default-use signal, which is stronger than implied guidance. There are no when-not conditions or named alternatives (e.g. when to use update_comment instead), so it stops short of full routing guidance.

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

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

Adds substantial context beyond the annotations (which only declare openWorldHint and idempotentHint): it discloses an auth requirement ('Requires an API key'), a side effect ('notify the people involved'), and the state-dependent rejection rules. These are the exact behavioral traits an agent needs before committing to a mutation.

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

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

Three tight sentences, front-loaded with the action and its side effect, then the auth requirement, then the failure conditions. No filler and nothing restated from the title or 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?

Covers the action, side effect, auth, and rejection rules for a two-parameter mutation with no output schema, which is nearly everything the agent needs. It does not describe the response shape or what happens if the ticket is already in the requested state, a minor gap given idempotentHint.

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 adds real meaning to the enum values: 'new' is create-only and rejected, and 'closed'/'invalid' are API-locked. That constrains which of the eight enum values are actually reachable targets.

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: 'Move a ticket to another workflow state', which is distinctly a transition operation rather than a general edit. It does not explicitly contrast itself with siblings like update_ticket, so an agent must infer that this is the state-machine-specific 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?

Gives concrete exclusions: 'new' is rejected here, and tickets in 'closed' or 'invalid' reject edits, so the agent knows two cases where the call will fail. It stops short of naming an alternative tool for those cases or stating prerequisites beyond the API key.

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

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

Beyond the annotations (idempotentHint, openWorldHint), the description discloses a real side effect — notifying people involved — and a state-based failure condition (locked tickets). That is meaningful behavioral context the structured fields do not carry, though nothing is said about permissions or depth of notification.

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 tight sentences with the primary action front-loaded and the failure caveat second. No filler or redundancy.

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

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

For a three-parameter mutation with full schema coverage and no output schema, the description covers action, side effect and blocking condition. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so ticketId, commentId and content are already documented in the schema. The description adds no extra parameter meaning, which is acceptable at the baseline.

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

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

The description names a specific verb and resource ('Replace the text of an existing comment'), which cleanly separates it from delete_comment and reply_to_ticket by the verb alone. It does not explicitly call out a sibling, but the operation 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?

It gives a concrete usage constraint: tickets in 'closed' or 'invalid' states are locked and reject edits. That tells the agent when the call will fail, though it does not explicitly compare against alternatives such as reply_to_ticket.

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

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

The description discloses behavior well beyond the annotations: partial-update semantics ('only the given fields are touched'), an important side effect (public→private generates an access token), and an auth requirement (API key needed). This is exactly the kind of mutation-specific context annotations cannot carry, and it is consistent with idempotentHint=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?

Three short sentences, each carrying distinct information: scope, partial-update behavior, side effect, and auth. The core action is front-loaded and 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?

For a mutation tool with no output schema, the description covers the fields, the partial-write semantics, the side effect, and auth. The only gap is that it does not clarify where the generated access token surfaces (return value vs. side channel) and gives no failure/conflict guidance for the unique-handle constraint.

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 each parameter (name, handle, isPrivate, projectId) is already documented in the schema. The description repeats the field list but adds no syntax, format, or constraint detail beyond what the schema provides, making the baseline 3 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 names a specific verb and resource ('Change name, handle or visibility of a project') and enumerates the mutable fields, so the agent knows exactly what the tool does. It does not explicitly distinguish itself from siblings like delete_project or create_project, but the verb makes the distinction self-evident.

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 rather than stated: 'Only the given fields are touched' tells the agent this is a partial update and that omitted fields are left alone, which is genuinely useful guidance. However, there is no explicit when-to-use versus alternatives, no prerequisite ordering, and no exclusions, so it stays at the minimum viable level.

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 only supply openWorldHint and idempotentHint; the description carries the real behavioral load by disclosing partial-update semantics ('only the given fields are touched'), the no-op rejection rule, the null-to-unassign convention, and the hard lock on closed/invalid tickets. These are exactly the mutation hazards an agent cannot infer from the annotations 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?

Three compact sentences, front-loaded with what can be changed, then the invariants, then the sibling pointer. Every clause carries actionable information with no filler.

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

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

For a six-parameter mutation tool with no output schema, the description covers what is editable, how partial updates behave, how to unassign, which states are locked, and where to go for state transitions. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description goes slightly beyond by spelling out the partial-update contract (unspecified fields are left alone) and restating the null-unassign behavior for assigneeUserId. It does not add format or range detail beyond the schema, so it sits just above baseline.

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

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

States a specific verb ('change') plus the exact editable field set (title, content, type, priority, assignee) on a named resource. It distinguishes itself from the nearest sibling by explicitly delegating workflow state changes to set_ticket_state, so an agent can route correctly 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?

Names the alternative tool (set_ticket_state) and the condition that selects it ('workflow state'), and states when the API will not accept the call at all (no-op updates, tickets in closed or invalid state). Both the when-to-use and when-not conditions are explicit.

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

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

With only openWorldHint in the annotations, the description carries most of the burden: it discloses the return value (file id) and the crucial behavioral fact that the upload is unlinked to any ticket, which dictates downstream flow. It does not mention permissions, size limits, or overwrite behavior for same-named files, so it is strong rather than complete.

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 tightly written sentences with zero filler; the purpose and the follow-up routing are both front-loaded and every clause earns its place.

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

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

Despite having no output schema, the description explains what is returned (file id) and how it should be used next. For a two-parameter, single-required upload tool this covers everything an agent needs to invoke it correctly.

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

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

Schema description coverage is 100%, so both filePath and fileName are already documented in the schema with their defaults and format ('absolute path', default name). The description adds no additional parameter meaning, making the baseline 3 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?

Specific verb+resource+outcome: 'Upload a local file into the file manager of the site and return its file id.' It is clearly distinguishable from siblings like download_attachment and add_ticket_attachments, and the return value is stated up front.

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 the post-upload state ('The file is not linked to a ticket yet') and routes the agent to the correct next tools ('pass the id to add_ticket_attachments or to create_ticket'). This is exactly the when-to-use/alternatives guidance the dimension asks for.

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