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

The description discloses important behavioral details: that contentBase64 is reliable only for payloads ≤ ~1 KB and that longer strings get truncated on the agent side. It also explains the return value ({attachment.url, attachment.markdown}) and clarifies that the attachment is not evidence and does not count toward closing the goal. These details go beyond the annotations (readOnlyHint: false, idempotentHint: false) and provide transparency about side effects and limitations.

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 well-structured with two clear paragraphs: the first outlines the purpose and return shape, the second addresses size limitations and alternatives. It is succinct without unnecessary repetition, and each sentence adds relevant information. The use of emphasis (— NOT evidence) and clear instructions keeps it focused.

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 the tool is a mutation (readOnlyHint: false) and not idempotent (idempotentHint: false), the description sufficiently covers usage context: it explains what the tool does, when to use it, and when not to use it (large files). It also explains the output format and how to integrate it ('paste markdown into the goal description'). No additional critical context 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?

The input schema covers all 7 parameters with descriptions, so the baseline is 3. The description adds value by explaining the size constraint on contentBase64 and clarifying its purpose ('Tiny files only — see description'). It also explains the usage of the returned markdown, which indirectly clarifies the purpose of filename and goalId. However, it does not elaborate on mimeType, createdBy, or contentSha256 beyond their schema descriptions, so some parameters lack additional 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 action ('Attach a small file') and the target resource ('to a GOAL as a description attachment'). It distinguishes this from evidence attachment by explicitly noting 'NOT evidence', and provides the output shape. The verb and resource are specific, and the sibling tool goal-attach-evidence is implicitly differentiated.

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 explicit usage guidance: it is for small files (mockup, diagram, screenshot, PDF) to be used as description attachments, not evidence. It also provides an explicit alternative for larger files: 'For anything bigger call goal-request-upload with goalId and stream the file with a single PUT'. This clearly tells when to use this tool vs alternatives.

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