Skip to main content
Glama

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.

  • asset_uuid links the finding to a resolved asset of any class. Find a name (or part of one) with GET /v1/assets using where=display_name == "" or display_name.contains(""); this searches every class and needs no class or key type. For an identity key whose kind the user provides (serial number, ARN, repo URL, digest), use GET /v1/assets/by-identifier?type=&value=; type is the identity key type, not the asset class, and class is optional. Count distinct asset_uuid values across the complete result: while there is a next_cursor, read the next page with cursor and unchanged filters and sort. A truncated or incomplete lookup cannot produce a link; with zero or multiple matches, omit asset_uuid and never guess. null removes the link and omission keeps it. It does not change asset_type or asset_identifier. For a finding whose asset_type is "host" or "asset", the link is the identity and cannot change (INVALID); create a new finding instead. Link the returned canonical asset_uuid as /environment/{asset_uuid}.

  • 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), ASSET_NOT_FOUND (asset_uuid is not an asset of this organization: resolve it again, never guess), 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).

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": {
      "uuid": "<uuid>"
    },
    "name": "updateFinding"
  }
}

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).
asset_uuidNoLink to a resolved tenant asset of any class, or send null to clear the link. Omit to keep it. Find names with GET /v1/assets using where=display_name == "<name>" or display_name.contains("<text>"). For a typed identity key use GET /v1/assets/by-identifier?type=<key type>&value=<value>; type is the identity key type, not the asset class; class is optional. Set only one distinct asset_uuid from a complete lookup. The asset pair does not change. Merged UUIDs link to the survivor; unknown or cross-tenant assets give ASSET_NOT_FOUND. For findings whose asset_type is 'host' or 'asset', the link is immutable (INVALID).
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. Changed1 schema field changed
    • addedInput schema / properties / asset_uuid
      Added value: +{
      +  "anyOf": [
      +    {
      +      "format": "uuid",
      +      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Link to a resolved tenant asset of any class, or send null to clear the link. Omit to keep it. Find names with GET /v1/assets using where=display_name == \"<name>\" or display_name.contains(\"<text>\"). For a typed identity key use GET /v1/assets/by-identifier?type=<key type>&value=<value>; type is the identity key type, not the asset class; class is optional. Set only one distinct asset_uuid from a complete lookup. The asset pair does not change. Merged UUIDs link to the survivor; unknown or cross-tenant assets give ASSET_NOT_FOUND. For findings whose asset_type is 'host' or 'asset', the link is immutable (INVALID)."
      +}
  2. First observed

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations supplied the description carries the entire burden, and it does: immediate write, no preview or confirmation, org-wide UI visibility, body REPLACES rather than appends, no evidence field, qualifier collisions produce CONFLICT, and host/asset links are immutable. It also enumerates every failure code with what each means for retry behavior (NOT_FOUND don't retry, PLAN_LIMIT wrote nothing).

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 first two paragraphs are tight and well front-loaded — scope, then the write-immediately warning. The subsequent asset_uuid bullet is a dense run-on that duplicates much of the schema description, and the enum and outcome sections restate constraints an agent can also read in the schema, making the whole definition longer than it needs to be.

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 an 11-parameter mutation tool with no annotations and no output schema, this covers everything an agent needs: identity immutability, replace-vs-append semantics for body and asset_details, dedupe-key collisions, cross-organization asset validation, and the full outcome set with retry guidance.

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 coverage is 91%, so the baseline is 3; the description still adds value beyond it by spelling out enum case-sensitivity rules, the full lowercase status set, and that resolution reasons like false_positive belong to a different field this tool cannot set. It also details the asset_uuid resolution workflow including the required pagination to a complete result before linking, though it partly restates the schema's asset_uuid guidance.

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' — then enumerates exactly which fields can change. It explicitly distinguishes itself from bulkUpdateFindings (sets of findings) and createFinding (different problem or different asset), so an agent can route without opening the 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?

Gives concrete triggering conditions ('the problem was fixed', 'it turned out not to apply', 'a vulnerability proved reachable') and names the alternatives with the condition that selects them: bulkUpdateFindings for described sets, createFinding for identity changes, getFinding to read before appending to body. The reopen case is called out as unusual and requiring confirmation.

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