Skip to main content
Glama
Sign In

Mallory

by ai.mallory.app
OverviewDiscussionsAdmin

updateFinding

Update ONE existing Mallory finding in place — its status, severity, confidence, title, summary, body, remediation, qualifier or asset_details. Use it when new information changes an already-filed finding: the problem was fixed, it turned out not to apply, a vulnerability proved reachable, corroborating intel changes how bad it is.

WRITES IMMEDIATELY to the caller's own organization's data, and the result is visible in the Mallory UI to everyone in that organization. There is no preview and no confirmation step — calling this tool IS the write. Only call it when the user has asked for the change.

  • uuid identifies the finding. Get it from listFindings or getFinding, or from a createFinding DUPLICATE outcome's existing_finding_uuid. Never construct or guess one.

  • ONE finding per call. To change status or severity across a SET of findings you can only describe ("dismiss all the unrotated-secret findings", "mark everything on foo/bar medium"), use bulkUpdateFindings — do NOT loop this tool over a selection.

  • The finding's identity — definition_slug, asset_type, asset_identifier — cannot be changed. A different problem, or the same problem on a different asset, is a new finding (createFinding).

  • body REPLACES the stored text rather than appending to it. To add to a finding, read the current text first with getFinding and send the combined text, or the prior detail is lost. There is no evidence field on update: new evidence goes into body as prose.

  • qualifier is part of core's open-finding dedupe key, so changing it can collide with another open finding on the same asset (CONFLICT).

In user-facing status messages, use "fixed" and "mark as fixed" consistently.

ENUM VALUES ARE CASE-SENSITIVE AND EACH FIELD HAS ITS OWN SET. severity is UPPERCASE (CRITICAL, HIGH, MEDIUM, LOW, INFO). status is lowercase with exactly three values: open, fixed, dismissed — "resolved", "closed" and "assigned" are not statuses, and neither are the resolution reasons (false_positive, accepted_risk, not_applicable, duplicate, fixed_externally, other), which belong to a separate field this tool does not set. Use "fixed" when the problem was remediated and "dismissed" when it is accepted or not applicable. Setting status back to "open" is allowed but unusual — the product has no reopen button — so confirm the user really means to reopen the finding.

OUTCOMES: either ok:true with the updated finding, or ok:false with a code — NOT_FOUND (no such finding in this tenant: do not retry, re-read the uuid), CONFLICT (an open finding already occupies that identity), INVALID (a rejected field, or no fields to change), PLAN_LIMIT (findings are not included in this tenant's plan — the request was fine, nothing is broken, nothing was written: say so and do not retry).

Input Schema

NameRequiredDescriptionDefault
bodyNoThe detail: what was found, how, and why it matters. Rendered as markdown. REPLACES the existing body — when adding to a finding (e.g. why it was escalated), read the current body first and send the combined text, or the prior detail is lost.
uuidYesUUID of the finding to update. Comes from a create outcome's existing_finding_uuid, or from GET /v1/findings.
titleNoAsset-scoped headline. Omit unless it is genuinely wrong.
statusNoLifecycle state. 'fixed' when the underlying problem is fixed, 'dismissed' when it is accepted or not applicable.
summaryNoOne or two sentences: what is wrong. Rendered as markdown.
severityNoNew severity for this instance, e.g. when reachability or corroborating intel changes how bad it is. Overrides the definition's default.
qualifierNoDiscriminator when one asset has several instances of the same definition. Part of the dedupe key — changing it can collide with another open finding (409).
confidenceNo
remediationNoConcrete steps to fix it, ideally a runnable command. Rendered as markdown.
asset_detailsNoFree-form structured context about the asset (region, account, owner, ...). Replaces the stored object.

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?

With no annotations, the description carries the full load and does so: it states the write is immediate with no preview or confirmation, that changes are visible org-wide, that body/asset_details replace rather than merge, and that qualifier edits can collide via the dedupe key. The outcome codes (NOT_FOUND, CONFLICT, INVALID, PLAN_LIMIT) with retry guidance go well beyond what annotations would have provided.

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 purpose, then side-effects, then per-field rules, then outcomes — a sensible escalation. It is long, and the enum casing paragraph partly restates what the schema enums already encode, which costs some conciseness, but nearly every sentence carries operational value.

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 10-parameter mutation tool with no annotations and no output schema, the description covers everything load-bearing: immutability of identity fields, dedupe collisions, replacement-vs-append semantics, the status vocabulary trap, and the full failure taxonomy including the non-retryable PLAN_LIMIT case.

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?

Schema coverage is already 90%, yet the description still adds real semantics: where uuid may and may not come from, that body replaces (with the getFinding read-then-merge workaround), that qualifier is part of the dedupe key, and that resolution reasons are a different field from status. It also flags the case-sensitivity of the differing enum casings.

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?

Opens with a specific verb and resource ('Update ONE existing Mallory finding in place') and enumerates the mutable fields. It explicitly separates itself from bulkUpdateFindings and createFinding, so an agent can route correctly without reading sibling schemas.

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?

Gives an explicit trigger ('when new information changes an already-filed finding'), an explicit permission gate ('Only call it when the user has asked for the change'), and named alternatives: bulkUpdateFindings for describable sets and createFinding for new problems or new assets. It even forbids the anti-pattern of looping this tool.

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

All Mallory toolsInspect
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