Skip to main content
Glama

Add several applications

add_applications

Add multiple job applications in one confirmed batch, each saved as not applied. Previews every row once, writes all or nothing, makes one backup, and undoes the whole batch in a single step.

Instructions

Add several new rows in one write, each with the not-applied status. Each item takes the arguments of add_application. The user sees one preview of every row and answers once. The write is all or nothing: if one item is refused (a duplicate, an unknown column), nothing is written and the error names that item. It makes one backup, so one undo_last_write removes the whole batch.

The tool writes only with the user's yes. The client may ask in its own confirmation dialog. Otherwise call with dry_run=true, show the preview to the user, and after they agree in a new message repeat the same call with confirm=. The write is refused if the tracker changed since expected_version. A backup is taken first, and undo_last_write reverts the write.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "items": "<items>"
    },
    "name": "add_applications"
  }
}

Input Schema

NameRequiredDescriptionDefault
itemsYesThe new rows, in the order to add them
confirmNoToken from the dry run the user approved. Not needed when the client shows the server's confirmation dialog
dry_runNoOnly show what would change, plus the confirm token; write nothing
expected_versionNo`version` from your last read; the write is refused if the file changed since

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.6.0

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false by default) by disclosing all-or-nothing atomicity, that the error names the offending item (duplicate, unknown column), and that a single backup is taken so one undo_last_write reverts the whole batch. It also explains the version-guard refusal and the two-step consent mechanism, which the annotations cannot express.

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

Conciseness4/5

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

Front-loaded with the action, then the atomicity/error behavior, then the consent flow — a sensible order with no filler. It loses a point for the closing sentence repeating backup/undo information already stated as "It makes one backup, so one undo_last_write removes the whole batch."

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

Completeness5/5

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

An output schema exists, so return values need not be explained, and the annotations cover the safety profile. The description still supplies everything else an agent needs for a multi-row write: atomicity, error surface, backup/undo semantics, version guard, and the full confirmation protocol.

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

Parameters4/5

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning the schema does not: the confirm token must be supplied in a new message after the user agrees, and dry_run is the intended first half of that handshake. "Each item takes the arguments of add_application" also routes the agent to the sibling schema for per-item fields.

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

Purpose5/5

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

States a specific verb and resource ("Add several new rows in one write") plus a distinguishing scope detail ("each with the not-applied status") and cross-references add_application for the per-item shape. An agent can immediately tell this apart from add_application (singular) and from set_status/set_statuses.

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

Usage Guidelines4/5

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

Gives an explicit decision path for the confirmation step: either the client shows its own dialog, or the agent calls with dry_run=true, shows the preview, and repeats with confirm=<token> after the user agrees in a new message. It also states the expected_version precondition. It stops short of explicitly saying "use add_application instead when adding a single row," leaving that to inference from the title.

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