Import Tracker issue attachment

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

Annotations already declare this is a non-read-only, non-destructive, open-world write. The description adds meaningful context beyond that: it is admin-only, the payload must be kept small because it travels as base64, and it returns the imported attachment. It does not cover conflict behavior, but the additions are substantive.

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

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

The description is compact and front-loads the core action. The size/CLI caveat, timestamp format, and return note are all relevant, though the timestamp format duplicates the schema and could arguably be trimmed.

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 five-parameter import mutation with full schema coverage and clear annotations, the description supplies the critical missing pieces: admin-only authorization, payload size constraint, and the fact that it returns the imported attachment. No output schema exists, but the return behavior is noted adequately.

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 schema already defines all five parameters in detail. The description restates the base64 nature of data and the created_at format but adds no new semantics or constraints beyond what the schema provides, matching the baseline for full coverage.

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

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

States a specific verb (Import) and resource (a file/attachment onto an issue) plus the distinguishing behavior of preserving original author and creation time. A capable agent can distinguish it from plain upload tools like tracker_attachments_upload, though no sibling MCP tool is named directly.

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

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

Provides some context: admin-only and a size caveat with an alternative CLI path for large files. However, it does not explicitly say when to choose this over sibling MCP tools such as tracker_attachments_upload or tracker_entities_attachments_attach, leaving the comparison implied.

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