Sergio by Serviche

Edit a handbook article

edit_handbook_article

Idempotent

Edits a handbook article as its Edit page does: title, content_md, category, tags, audience, bucket, is_published, exclude_from_suggestions. Send only the fields to change (sop_id from read entity sops); content_md replaces the whole body, so read the article in full (read sops with id) and send all of it with the change in place. Saving supersedes pending suggestions on it. 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. If the article is in a training module with quiz questions, say in your answer that its questions may need regenerating (generate_training_questions with regenerate). Pass the same idempotency_key when retrying.

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": "edit_handbook_article"
  }
}

Input Schema

Name	Required	Description
`tags`	No
`title`	No
`bucket`	No
`sop_id`	Yes
`audience`	No
`category`	No
`content_md`	No
`is_published`	No
`idempotency_key`	Yes	Your 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.
`exclude_from_suggestions`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 8, 2026

TDQS

A4.3/5.0

Behavior3/5

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

Beyond the annotations, this tool adds genuinely important behavior: content_md replaces the entire body, so the caller must read and resend full content; saving supersedes pending suggestions; retries must reuse the same idempotency_key; and quiz questions may need regenerating. However, it does not state what permissions are needed, what happens to fields omitted from the payload, or what the tool returns, and no output schema exists to fill that gap.

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?

Core mechanics are front-loaded in the first two sentences, so the essential contract is readable immediately. The remainder is dense but largely earns its place as behavioral policy; a few clauses run long and pack multiple rules into one sentence, which slightly hurts scannability.

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?

For a 10-parameter mutation with no output schema and no field-level documentation, the description covers the risky parts: full-body replacement, suggestion supersession, quiz regeneration warnings, and idempotent retries. It stops short of describing the response payload or partial-update semantics for omitted fields, which would matter in the absence of an output schema.

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?

With only 10% schema description coverage, the description must carry most of the semantic load, and it does explain the two hardest parameters well: sop_id comes from the sops read entity, and content_md is a full-body replacement requiring a read-then-resend pattern. It also maps audience values to concrete user language, but it never explains what bucket A/B/C means or what exclude_from_suggestions does, leaving those columns partly guessable.

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 first sentence names a specific verb and resource and enumerates the mutable fields: 'Edits a handbook article as its Edit page does: title, content_md, category, tags, audience, bucket, is_published, exclude_from_suggestions.' It also implicitly separates this tool from create_handbook_article and archive_handbook_article by scoping it to in-place edits of an existing sop_id.

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 routing rules: search sops by topic first, edit an existing article with full content_md or use draft_handbook_edit, and create a new article only when nothing fits, with a required explanation of the closest match. It also supplies conflict-resolution policy (audience from the person's words, ask one line when ambiguous, tie-breaking rules for two matching places) and forbids a confirmation question before editing.

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

All Sergio by Serviche tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?