evidence_attach_file

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It indicates a mutation ('Attach') but does not explain side effects, whether repeated attachments are allowed, permission requirements, record-resolution behavior when both id and kod are supplied, or what happens if neither identifier is provided.

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?

One sentence containing exactly the core action, target, and scope with no filler. The essential information is front-loaded and every word 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?

The description omits a critical precondition: a target record must be identified somehow, but both id and kod are optional in the schema and neither is required. An agent could easily attempt a call with only evidence and filepath, which cannot succeed. The output schema exists, so return-value documentation is not the gap, but record identification guidance 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 schema already documents every parameter. The description adds little beyond reinforcing 'local file' and 'any evidence'; it does not clarify the relationship or mutual exclusivity of id and kod, but the schema already labels kod as an alternative to id.

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 uses a specific verb and resource: it attaches a local file to a record in any AbraFlexi evidence. It clearly distinguishes this from sibling attachment tools like evidence_get_attachment, evidence_download_attachment, and evidence_delete_attachment by naming the attach action.

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 clear context for when to use the tool: when a local file needs to be attached to a record, across any evidence type. It does not explicitly name alternatives or exclusions, but the attach action uniquely matches this tool among the siblings, so confusion is unlikely.

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