Skip to main content
Glama

Sergio by Serviche

Have Sergio draft an article edit

draft_handbook_edit
Idempotent

Asks Sergio to draft an edit to an article, as the article's Ask Sergio does: with context, the smallest change that does what it says; without, a general cleanup. The draft waits as a pending version (review_handbook_edit approves or rejects it). When the person gave the exact words to add, edit_handbook_article with them is the direct change; use this when they asked for a rewrite or cleanup. Before adding anything to the handbook, search the sops read entity by the topic (search finds by meaning): when an article already covers it, put the new text into that article (edit_handbook_article with its full content_md, the new lines placed where they belong, or draft_handbook_edit) instead of a new one; create a new article only when none fits, and say which closest article you found and why it did not fit. Audience comes from the person's words: cleaner SOPs, cleaning standards or staff = cleaner; policies, office or VA = va; when the words do not say, ask in one line. Ask which place, in one line naming both, when two places fit the person's words equally well: two articles, or two training modules that both match (two new-hire modules are a tie whatever their status, draft or published); a place the person named outright is never a tie. The proposed change is the confirmation, so never ask "should I add this?" first. Pass the same idempotency_key when retrying; a repeat returns the same draft without asking the model again.

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": {
      "sop_id": "<sop_id>",
      "idempotency_key": "<idempotency_key>"
    },
    "name": "draft_handbook_edit"
  }
}

Input Schema

NameRequiredDescriptionDefault
sop_idYes
contextNo
idempotency_keyYesYour id for this operation (8-128 of A-Z a-z 0-9 . _ : -). Reuse it on every retry of the same operation; use a new one for a new operation.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare non-read-only, idempotent, non-destructive, but the description adds the non-obvious behavior: the output is a pending draft gated by review_handbook_edit, and retrying with the same idempotency_key returns the same draft without re-invoking the model. It also states that the proposed change itself serves as confirmation, so no pre-confirmation question should be asked.

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

Conciseness3/5

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

The core routing information is front-loaded, but the single dense paragraph bundles tool behavior with broader agent workflow policy (searching the sops entity, audience mapping, tie-breaking rules, phrasing of confirmation questions). Much of it earns its place as routing guidance, but the run-on length makes it harder to parse than a short structured statement would be.

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

Completeness4/5

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

There is no output schema, and the description does state the key return characteristic (a pending draft reviewed by review_handbook_edit) plus retry behavior. It does not say what identifier or payload the draft response carries, which leaves a small gap for a mutation tool with side effects.

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 only 33%, and the description compensates by explaining what 'context' does behaviorally (with context = smallest change that does what it says; without = general cleanup), which the schema does not say. The retry semantics of idempotency_key are reinforced, though sop_id is never explained (e.g. that it must be an existing article id).

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 opening sentence gives a specific verb and resource ('asks Sergio to draft an edit to an article') and immediately distinguishes the outcome (a 'draft' that 'waits as a pending version') from the direct-write sibling edit_handbook_article and from the review step review_handbook_edit. An agent can pick between these three tools without opening any schema.

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 explicitly states the selection rule: exact words to add -> edit_handbook_article; a request for a rewrite or cleanup -> this tool. It also specifies when to search the sops entity by meaning before adding anything, when to edit an existing article instead of creating one, how to derive audience, and when to ask a one-line tie-breaking question.

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