上传 TAPD 缺陷附件

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

No annotations provided. Description discloses file size limit, supported types, and base64 requirement. Does not mention authentication, rate limits, or side effects beyond creating an attachment. Adequate but not exhaustive.

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 concise sentences, front-loaded with core action and constraints. Every sentence adds value: type/size, encoding method, usage recommendation, and verification hint.

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 key aspects: what it does, input format, usage context. Lacks output/response details, but no output schema exists. Suggests verification via another tool. Sufficient for the tool's complexity.

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

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

Schema coverage is 100%, but description adds value: explains base64 encoding rationale, confirms boolean requirement, workspace_id lookup guidance. Exceeds baseline 3 by providing practical context.

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

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

The description clearly states the tool uploads files to a bug's attachments, specifies supported types and constraints, and differentiates from siblings by noting that videos/screenshots should use this tool rather than embedding in descriptions.

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

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

Provides explicit guidance: use base64 encoding (no local path), confirmed must be true, and videos/screenshots belong here. Also suggests verifying with tapd_get_bugs. Lacks explicit 'when not to use' but contrast with siblings is implied.

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