attach_file_to_request

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

No annotations are provided, so the description carries full burden. It explains that the attachment can be public or internal and allows an optional comment, but does not disclose side effects, auth requirements, or constraints (e.g., file size limits, whether the request must be open). This is adequate for a simple mutation but lacks depth.

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 appropriately sized, uses a clear docstring format with an Args section, and front-loads the purpose. Every sentence serves a purpose, with no redundancy or wasted words.

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

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

The tool has an output schema (not shown) and the description does not need to explain return values. It covers prerequisites (calling upload first), parameter details, and the optional comment. However, it omits constraints like file size limits or permissions. Given no annotations and 0% schema coverage, the description does a solid job, but some completeness 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 0%, so the description must compensate. It thoroughly explains each parameter: issue_id_or_key as key or numeric ID, temp_attachment_id as output of upload, public as visibility, and comment as optional text. This adds essential meaning beyond the schema.

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

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

The description clearly states that the tool attaches a previously uploaded temporary file to a customer request, specifies the prerequisite tool (upload_temporary_attachment), and distinguishes it from the sibling upload tool by mentioning the required context (issue and temp ID).

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

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

The description provides explicit instructions to call upload_temporary_attachment first and explains each parameter's role. However, it does not explicitly state when not to use this tool or offer alternatives, but the prerequisite guidance and parameter explanations give sufficient context.

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