Skip to main content
Glama

Propose changes to records

propose_changes

AI Agents (inside one system): Use whenever the person asks to change records in a system whose AI agent may change them: every change goes through here first, and nothing is written. Pick one action and give one item per record, at most 25. set_fields: fills, corrects, empties or makes records with the fields describe_record_type lists (type, and id unless it makes a new record; set holds field keys and new values, clear the keys to empty). update_fields: New values for fields of a record that exist in the person's own system, such as a lead status or a custom field, by their own names. (type, id, fields). move_stage: A record moved to another stage or status of its pipeline, such as a deal to proposal sent or to won; a won or lost stage closes the record. (type, id, stage; optional pipeline). add_note: A note on a record's timeline in the person's system. (type, id, text; optional at, user). add_task: A task or follow up on a record in the person's system, such as a call next week; the system may notify the user it is assigned to. (type, id, subject, due_at; optional notes, priority, task_kind, done, user). link_records: Two records linked in the person's system, such as a contact to a deal, or an existing note or task to another record; nothing changes when they are linked already. (type, id, other_type, other_id). unlink_records: The link between two records removed; both records stay as they are, and only the person can approve it. (type, id, other_type, other_id). Nothing is written yet: the answer shows, per record, what it holds now and would hold after, plus a proposal id. Show it to the person, say so first when something would be sent to the people in their system, ask whether to go ahead, and only then call apply_proposal; when needsApproval is true, share the approve link instead. Not for reading (use search_records or get_record). Never deletes and never records a payment.

Input Schema

NameRequiredDescriptionDefault
itemsYesOne object per record, at most 25, with the values the action takes.
actionNoWhat to propose; set_fields when left out.set_fields
systemYesWhich AI agent: the system's id from list_ai_systems, or the name of the system or its connection. Ask the person which AI agent they mean unless they named it in this conversation; never pick one yourself.

Output Schema

NameRequiredDescriptionDefault
noticeNo
changesYes
systemIdYes
warningsYes
expiresAtYes
approveUrlYes
proposalIdYes
systemNameYes
needsApprovalYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.9/5.0
Behavior5/5

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

The description adds substantial context beyond the annotations: nothing is written, the response contains current and proposed values plus a proposal id, the agent must show it to the person and ask before applying, and approval-link handling is described. It also discloses that unlink_records requires person approval and that the tool never deletes or records payments.

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?

The description is long, but the tool is complex and multi-action, so most of the length is justified. It is front-loaded with usage and action definitions, though the dense action-definition block could be structured more cleanly.

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?

For a complex proposal tool with an output schema, the description covers purpose, action selection, item limits, approval handling, and the handoff to apply_proposal. There is no material gap that would prevent an agent from invoking it correctly.

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

Parameters5/5

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

Although schema coverage is already 100%, the description adds action-level semantics that the schema does not fully convey: what each action is for, how set_fields differs from update_fields, that move_stage can close a record, and that link_records is a no-op when the link already exists. It also frames record-item selection around the chosen action.

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?

The description states a specific verb and resource: it proposes record changes rather than performing them. It clearly distinguishes itself from read tools and from apply_proposal by saying every change goes through here first and nothing is written yet.

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

Usage Guidelines5/5

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

It gives explicit when-to-use guidance ('Use whenever the person asks to change records...'), names the read alternatives ('use search_records or get_record'), and explains the follow-up workflow to apply_proposal. It also states constraints such as one action, one item per record, and at most 25 items.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources