Skip to main content
Glama

List organisation audit logs

list_organisation_audit_logs
Read-only

Read the organisation's audit trail, newest first (the twin of GET /org/organisation/audit-logs and ankra org audit-logs): who did what, to what, and whether it worked. Each entry carries timestamp, actor (type is agent for an Ankra AI run, service_account for a token, system for the platform, human for a person; agent_name and run_id name the run), action_type, resource_type and resource_id, target (kind, name, namespace), outcome (status succeeded, failed or unknown; unknown means the writer recorded no success marker, not a failure), the cluster it belongs to, and the recorded details. Filter by search text, user_id, action_type, resource_type, cluster_id, actor_type, outcome, agent_task_id and a start_date/end_date window; page with page and page_size (default 25, at most 100). total and total_pages say how many match. The trail is organisation-wide, so a caller confined to a project is refused. Read-only; needs audit.read (organisation owners and admins).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_organisation_audit_logs"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNoPage number, from 1.
searchNoFree text matched against the actor's email, action_type, resource_type, resource_id and the recorded details.
outcomeNoOnly entries with this outcome.
user_idNoOnly entries written by this member (user id from list_organisation_members).
end_dateNoLatest entry time, a date (2026-12-31, which includes that whole day UTC) or an RFC 3339 timestamp. Send the same date as start_date and end_date to read one day.
page_sizeNoEntries per page, 1 to 100 (default 25).
actor_typeNoOnly entries by this kind of actor.
cluster_idNoOnly entries that belong to this cluster of the organisation, including clusters that have since been deleted (cluster_id and cluster_is_deleted on an entry name them).
start_dateNoEarliest entry time, a date (2026-12-31, from its midnight UTC) or an RFC 3339 timestamp.
action_typeNoOnly entries with exactly this action_type.
agent_task_idNoOnly entries written by the runs of this agent.
resource_typeNoOnly entries with exactly this resource_type.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / cluster_id / description
      Previous value: -"Only entries that belong to this cluster, including clusters that have since been deleted."New value: +"Only entries that belong to this cluster of the organisation, including clusters that have since been deleted (cluster_id and cluster_is_deleted on an entry name them)."
    • changedInput schema / properties / end_date / description
      Previous value: -"Latest entry time, a date (2026-12-31) or an RFC 3339 timestamp."New value: +"Latest entry time, a date (2026-12-31, which includes that whole day UTC) or an RFC 3339 timestamp. Send the same date as start_date and end_date to read one day."
    • changedInput schema / properties / start_date / description
      Previous value: -"Earliest entry time, a date (2026-12-31) or an RFC 3339 timestamp."New value: +"Earliest entry time, a date (2026-12-31, from its midnight UTC) or an RFC 3339 timestamp."
  2. Added

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=true; the description goes well beyond that by stating newest-first ordering, pagination defaults and caps, the authorisation model, the project-scope refusal, and the crucial interpretation that outcome 'unknown' means no success marker was written rather than a failure. Those are behavioral facts an agent could not recover from the annotation or schema.

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 scope and source-of-truth framing is front-loaded, and the entry-shape, filter list, pagination and permission clauses each carry real information. It is a dense single block that would scan better as short segments, but there is little outright waste.

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?

With 12 optional parameters and no output schema, the description compensates by enumerating the returned entry fields (timestamp, actor, action_type, resource_type/resource_id, target, outcome, cluster, details) and the totals, so an agent knows what comes back and which filters exist. Nothing material for correct invocation is missing.

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 100%, so the schema baseline would be 3; the description still adds genuine meaning by explaining what each actor_type value denotes (agent for an AI run, service_account for a token, system for the platform), what outcome 'unknown' implies, and how total/total_pages relate to paging. It does not detail date-window composition or search-field matching beyond what the schema already says.

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 ('Read the organisation's audit trail, newest first') and anchors it to known twins (GET /org/organisation/audit-logs and `ankra org audit-logs`). The 'who did what, to what, and whether it worked' framing distinguishes it from log-oriented siblings such as query_logs or get_pod_logs by making clear this is the organisation-wide audit trail.

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

Usage Guidelines4/5

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

Gives a hard scoping constraint — the trail is organisation-wide, so a project-confined caller is refused — plus the required permission (audit.read, owners/admins), which tells an agent up front whether it can call this at all. It does not explicitly name an alternative tool for narrower log queries, so it stops short of full when-to-use/when-not routing.

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.