Analyze Salesforce Apex debug logs and manage org debug logs, anonymous Apex, and trace flags.
Summarize a log: transaction duration, category time, governor limits, completeness, exceptions, flow errors, and fatal errors.
Rank slow operations by self time or retained heap, with filtering, grouping, paging, and query plans.
List governor-limit risks nearest their ceiling.
Search log events such as USER_DEBUG, validation rules, statements, or events under a method.
Execute anonymous Apex in a Salesforce org, save the debug log, and return its path for analysis.
List org-stored debug logs with filters, sorting, and cursor paging, then download logs by ID or latest N.
Create trace flags for users, classes, or triggers with configurable duration and debug levels.
Run analysis locally over stdio without API keys; org tools require Salesforce CLI authentication and support production safety, deny lists, read-only mode, and no-Apex-execution flags.
Provides tools to analyze Salesforce Apex debug logs for performance bottlenecks, slow methods, and governor limit usage, and allows executing anonymous Apex against Salesforce orgs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Apex Log MCP Server Find the top 5 slowest methods in this debug log and their durations"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Server to Analyze Salesforce Apex debug logs from your AI assistant. Finds slow methods, governor limit risks, and where a transaction spent its time. In your org, runs anonymous Apex, fetches logs, and sets trace flags.
Instead of scrolling thousands of log lines, ask what's slow and why. Uses the same Apex log parser as the Apex Log Analyzer VS Code extension.
Requires Node.js 22 or later. Add this to your MCP client config (claude_desktop_config.json, VS Code mcp.json, and so on):
{
"mcpServers": {
"apex-log-mcp": {
"command": "npx",
"args": ["-y", "@certinia/apex-log-mcp"]
}
}
}In VS Code mcp.json, use "servers" in place of "mcpServers".
Then ask your assistant to analyze a log. The org tools - apexlog_execute_anonymous, apexlog_list_org_logs, apexlog_get_org_logs and apexlog_create_trace_flag - also need an org authenticated with the Salesforce CLI.
Related MCP server: Log Reader MCP
"Give me a summary of this debug log"
"Show me the 5 slowest methods in the default namespace"
"Are we approaching any governor limits in this transaction?"
"What did my System.debug calls print?"
"Run this Apex against my scratch org and analyze the performance"
"Run it again with database logging at FINEST"
"Find the latest debug log for integration@acme.com and summarize it"
"Why are there no logs for this user?"
Keeping the server connected costs ~2,445 tokens, 1.2% of a 200K context. See Token Cost.
The org tools use the default org of the project in your client's first root, unless you pass targetOrg. A client that declares no roots gets the default org of the server's working directory, or the global default org. When the server cannot read the roots a client declares, each org tool needs targetOrg, since the project's default org cannot be found. That happens when the client uses MCP protocol version 2026-07-28, when the roots cannot be read - for example, the client does not answer in 5 seconds - or when no root is on this machine.
Each tool returns its result in TOON, and an error as plain text.
A 0 means none, not "not measured". Only what did not happen is left out: fatal errors, lost log content, query plans. Durations are in milliseconds to 3 decimal places, percentages to 1.
An analysis tool that pages gives matchedCount, the rows that matched in all, and, while more remain, nextOffset, the offset of the next page.
The server runs as a local process started by your client over stdio, with no API keys. The analysis tools make no network calls. The server keeps the last parsed log for 5 minutes after its last use, so follow-up questions on that log are faster.
Ranks what a log spent its time on by self time - code units, methods, queries, searches, DML, flows and workflows in one table.
A default response returns:
capturedAt - {debugCategory, level}
operations - {debugCategory, type, name, namespace, callCount, durationTotalMs, durationSelfMs, durationSelfMaxMs, selfPercentage, soqlCount, dmlCount, soslCount, rowCount, thrownCount}
queryPlans - {operationRow, leadingOperationType, relativeCost, cardinality, sObjectCardinality}
Each response also gives durationTotalMs for the whole transaction, and returnedSelfPercentage for the share these rows account for.
durationSelfMaxMs is the slowest single call in a grouped row. Read it against durationSelfMs to tell one bad call from many small ones. It is absent when the row is already one call.
Two columns say what a row is, both taken straight from the log:
debugCategory - what Salesforce stamped on the event. It decided whether the event was logged at all, and it is the spelling apexlog_execute_anonymous takes.
type - the event type. The category cannot imply it: SOQL_EXECUTE_BEGIN, SOSL_EXECUTE_BEGIN and DML_BEGIN all sit under database.
Watch for ENTERING_MANAGED_PKG. It is time a package spent where the log shows nothing, and it is often most of a transaction.
sortBy: "heapSelfNetBytes" ranks by retained heap instead of time, adding that column and returnedHeapPercentage. Both are absent otherwise. The figure is signed, so a row that released more than it took reads below zero. Heap is logged only at apexCode FINER and above, so check the apexCode row of capturedAt before trusting a zero.
capturedAt gives the level each category in the returned rows was logged at.
queryPlans is what the query optimizer decided about the queries behind those rows. A relativeCost above 1 means it will not treat the query as selective. Plans are absent when the log explained none, because explain lines need database FINEST.
operationRow points at a row of operations, counting from 1. Under a namespace, callerNamespace or debugCategory grouping a row is not one query, so the plan carries the query text in name instead.
Parameter | Type | Required | Description |
| string | Yes | Absolute path |
| ( | No | Rank only these debug log categories |
| string[] | No | Rank only these log event types, e.g. SOQL_EXECUTE_BEGIN, DML_BEGIN, METHOD_ENTRY |
| string[] | No | Rank only these namespaces |
| number | No | Drop operations below this self time (default: 0), whichever sortBy is used |
| number ≥ 0 | No | Page size (default: 10); fewer if the page would be too large |
| number ≥ 0 | No | Ranked rows to skip (default: 0): the last page's nextOffset |
|
| No | Fold repeats into one row; default name. callerNamespace attributes platform DML to the package that drove it. debugCategory folds a namespace's event types together and so states no type or name. none ranks each call on its own. A grouped durationTotalMs is what the transaction takes back if the group never runs - never sum it across rows. |
|
| No | Default durationSelfMs. heapSelfNetBytes adds that column. |
How long the transaction ran, where the time went, what it consumed, and whether the log is complete. Start here.
fatalErrors - {message, frames}
governorLimits - {limit, used, max}
limitsByNamespace - {namespace, limit, used}
categories - {debugCategory, level, operationCount, durationSelfMs, selfPercentage}
All thirteen governor limits are listed.
limitsByNamespace shows what each namespace consumed. This is how you see a managed package spending your CPU time. It has no ceiling column, because a ceiling is per limit for the whole transaction and already sits in governorLimits.
categories covers all eleven, each with the level it was captured at, because the level is what a zero means:
database,NONE,0 - the queries were not logged.
database,FINEST,0 - no queries ran.
dataAccess,"",0 - the log's header declared no level for it, which most logs do not.
dataAccess, wave and validation are always zero. No timed event carries them.
A last unattributed row holds the time no event spans, such as the time before the transaction starts. With it, the rows add up to the whole log.
truncated says whether the log is complete. In a partial log, every figure is a floor. Where the platform cut it, truncatedBy says how - skipped-lines for a hole, max-size for a missing tail - and skippedBytes says how much went. Both are absent when a log merely stops mid-frame.
thrownCount counts the exceptions thrown.
exceptions appears when something was thrown: {message, thrownIn, lineNumber, thrownCount}, one row per message, most thrown first. The table stops at 20 rows. exceptionGroupCount counts the messages, so a cut table says so. The log does not say whether a throw was caught.
message is the first line of the exception, cut at 200 characters. Two messages that differ only after that share a row.
thrownIn and lineNumber say where the message was first thrown. thrownIn is the nearest method, constructor or code unit that the log recorded.
Below APEX_CODE,FINE the log records no method. Then thrownIn can be a code unit while lineNumber is a line in a method that it called.
A managed package states its line as EXTERNAL.
flowErrorCount counts the flow elements that failed. A flow can fail with no exception and no fatal error.
fatalErrors appears once per failure that ended the transaction, with the innermost three frames and a trailing … where there were more. It is the only field that says a transaction did not finish, because a fatal error need not breach any limit.
Parameter | Type | Required | Description |
| string | Yes | Absolute path |
The governor limits nearest their ceiling, worst first.
capturedAt - {debugCategory, level}
atRisk - {limit, used, max, usedPercentage}
threshold is reported beside the rows, so an empty table means nothing reached it rather than that the answer is missing.
capturedAt gives the level that gated each returned limit. Every limit but heap comes from apexProfiling; heapSize comes from apexCode.
Parameter | Type | Required | Description |
| string | Yes | Absolute path |
| number | No | Minimum usedPercentage to report (default: 80) |
Searches a log's events in log order, for what the other tools rank or total: what the code printed (USER_DEBUG), the validation rules, the statements, or every event under one method. Filters combine.
capturedAt - {debugCategory, level}
events - {eventIndex, parentEventIndex, type, namespace, lineNumber, text}
A row says what an event is and where it sits, not what it cost: rank the time with apexlog_list_slow_operations. eventIndex names an event and parentEventIndex the one it sits under, so a row found here can be opened up with parentEventIndex. An exit line is a row only where the log lost its entry, and then it is the one record that the method ran.
Text past 400 characters is elided. Ask for one event by eventIndex to read up to 30,000 characters of it. contains searches a row's text before elision, and a long row is cut around the match. For plain text, grep the saved .log: it is cheaper. This tool earns its tokens on event types, nesting, and clients with no shell.
capturedAt comes on the first page, or with one event asked for:
When every type named matched, or you asked for one event, it gives the levels of the categories the matches came from.
Otherwise, or when those name no category the header declared, it gives every level the header declared.
No USER_DEBUG on a log at apexCode NONE means the log did not capture debug output, not that the code printed none.
Parameter | Type | Required | Description |
| string | Yes | Absolute path |
| string[] | No | Only these log event types, e.g. USER_DEBUG, VALIDATION_RULE |
| string[] | No | Only these namespaces |
| string | No | Only events whose text holds this, ignoring case |
| number ≥ 0 | No | Only this event, with more of its text |
| number ≥ 0 | No | Only events below this one |
| number ≥ 0 | No | Page size (default: 50) |
| number ≥ 0 | No | Rows to skip (default: 0): the last page's nextOffset |
Runs anonymous Apex against an authenticated org, saves the debug log locally, and returns the path. Pass that path to any analysis tool. The Apex runs as the targetOrg user, with that user's permissions. Its DML commits when the run succeeds; a compile failure or an uncaught exception rolls it back.
Give exactly one of apex or apexFilePath, as sf apex run --file takes - for example a script under scripts/apex/. A file outside the roots your client declares is refused, as is anything but a regular file. When the server cannot read the roots your client declares, a file is refused: see Tools Reference. A path costs a few tokens, where inline Apex is read and then written out again. A production confirmation shows the Apex the file holds, not its path.
The response gives filePath, fileSizeBytes, org (the username, with its alias if set), orgType, succeeded, exceptionMessage when the Apex threw, durationTotalMs, levelsSource, levelsOverridden, outputDirCreated, and a warning when something needs your attention.
When the targetOrg user has no live USER_DEBUG or DEVELOPER_LOG trace flag, the run adds one and deletes it after the run. The debug level that flag uses, Apex_Log_MCP_Debug_Level, stays in the org for the next run.
Logs go to .apex-log-mcp/ by default - add it to your .gitignore. Production orgs are gated: see Production safety.
Parameter | Type | Required | Description |
| string | No | The anonymous Apex to execute, or use apexFilePath |
| string | No | Absolute path to a file of anonymous Apex |
| string | No | Alias or username of the target Salesforce org. Uses the project default if not specified. |
| string | No | Log directory (default: .apex-log-mcp/ in the first client root, else cwd) |
|
| No | This run's log levels. Omit for the user's trace flag levels, else the defaults; "default" forces the defaults; a bare level sets every category; an object sets the named categories over the defaults. Defaults: apexCode, apexProfiling, visualforce, workflow FINE; callout, system, validation DEBUG; database FINEST; nba, wave INFO. |
An object debugLevel looks like this:
{ "database": "FINEST", "apexCode": "FINE" }Set a USER_DEBUG trace flag on your user - in Setup, for example - and every run you start without debugLevel logs at its levels; your flag is never changed. levelsSource in the response says where a run's levels came from: traceFlag, default or request. A live DEVELOPER_LOG trace flag on your user outranks debugLevel and the defaults, so the run takes its levels and levelsSource is traceFlag. levelsOverridden says when the log carries levels other than the ones levelsSource names.
Lists the debug logs stored in an org - a slow UI action, an integration user's request, a Queueable - so an agent can find one it did not run itself. Filters, sorting and paging all run in the org, so a page costs what limit asks for, however many logs the org holds.
matchedCount is how many logs the filters match. exceptionMessage says why a log failed. A cursor pages past the 2,000 rows SOQL's OFFSET stops at; nextCursor is absent on the last page.
Parameter | Type | Required | Description |
| string | No | Alias or username of the target Salesforce org. Uses the project default if not specified. |
| string | No | Username whose activity was logged |
| string | No | Part of the operation, any case, e.g. "aura" for /aura |
| string | No | e.g. "Api" or "Application" |
| boolean | No | true: succeeded logs only; false: failed logs only |
| string | No | ISO 8601 with a zone, e.g. 2026-10-09T09:00:00Z |
| string | No | |
| number ≥ 0 | No | |
|
| No | Descending (default: startTime) |
| number 1–200 | No | Page size (default: 20) |
| string | No | nextCursor from the previous page |
Downloads logs by ids or the newest latest, as sf apex get log does. Returns each saved path, for the analysis tools.
A log already saved under outputDir is not downloaded again, since a stored log never changes; downloaded says which were. A log that cannot be downloaded is a row in failed, with the cause, and the rest still save. If apexlog_get_summary reports truncated: true with no truncatedBy for a saved log, the file may have been cut off while it was written: delete it and call this tool again. It reports progress as each log saves. Cancelled, it starts no more downloads; those already running finish and are saved. If the org's login stops working, it also starts no more: those ids are rows in failed, and warning says how to log in again.
Parameter | Type | Required | Description |
| string | No | Alias or username of the target Salesforce org. Uses the project default if not specified. |
| string[] (1–25 items) | No | Log ids, from apexlog_list_org_logs |
| number 1–25 | No | The newest N logs, in place of ids (default: 1) |
| string | No | Log directory (default: .apex-log-mcp/ in the first client root, else cwd) |
Starts logging a user, so an integration user's requests reach the org's logs, for apexlog_list_org_logs to find. A flag on a class or trigger stores no log itself: it sets the levels of that code's work in the logs a user's flag stores. A user is traced as USER_DEBUG; a class or trigger as CLASS_TRACING.
The durationMinutes maximum is a minute short of a day, because Salesforce refuses a flag of a full day. The debug level the flag uses stays in the org after the flag ends, for the next flag at the same levels. An object debugLevel takes the form shown under apexlog_execute_anonymous.
Every transaction a traced user runs while the flag lives is stored, which can fill the org's 1,000 MB of log storage: when it is full, no one can set a flag until logs are deleted in Setup > Debug Logs, or expire after 24 hours. When the entity already has a flag of its type whose time overlaps the new one, the call is refused and names it, with its levels, its expiry and the sf command that deletes it - a flag is never changed here. Against a production org, the call asks first, naming the entity, the levels and the minutes.
Parameter | Type | Required | Description |
| string | No | Alias or username of the target Salesforce org. Uses the project default if not specified. |
| string | Yes | A username or user id, or a class or trigger name (ns.Name if namespaced) |
|
| No | A level for every category, or the named ones over apexlog_execute_anonymous's defaults (default: those) |
| number 1–1439 | No | How long it logs (default: 30) |
Every request carries every tool definition, whether you call them or not. Each figure below is a whole definition: name, title, description, input schema and annotations.
Tool | Tokens |
| ~524 |
| ~424 |
| ~349 |
| ~330 |
| ~313 |
| ~200 |
| ~155 |
| ~150 |
Total | ~2,445 (1.2% of a 200K context), +60% vs 1.x ~1,529 |
No single row compares with 1.x: per tool it would compare different tools, since apexlog_list_slow_operations replaced one that took three selection parameters and ranked methods where this one takes eight and ranks every timed event. The total is above 1.x because of the three org tools, which reach logs and trace flags 1.x could not, and apexlog_search_events, which reaches the events 1.x parsed and dropped.
The 4 tools that replaced 1.x's now cost ~1,253 tokens.
A call itself is a tool name and a log path, so what a call costs is what it returns.
Cost barely grows with the log size. The figures below are measured against a 40 KB slice of the Apex Log Analyzer sample log.
Tool | Response | 1.x | Change |
| ~342 | ~293 | +17% |
| ~400 | ~408 | -2% |
| ~35 | ~84 | -58% |
| ~881 | - | - |
The Quick Start config gives you every tool.
Every org tool reads the org's type, and a --deny-orgs type: entry can refuse any of them. Only the two tools that change an org - apexlog_execute_anonymous and apexlog_create_trace_flag - use the type to decide whether to ask first:
Org type | Identified by | Behaviour |
|
| Runs |
|
| Runs |
| Not a sandbox, has a trial expiry | Runs |
| Developer Edition | Runs |
| Anything else | Confirmation required |
| The org could not be queried | Confirmation required |
For a production org, --allow-production-orgs skips the confirmation. Otherwise the server asks you to confirm, naming the org and what the call would do - for Apex, all of it with its size. Apex over 10,000 characters is refused rather than cut, so it needs the flag. Confirmation needs a client that supports elicitation; without one the call is refused, and the message names both ways to proceed. Each confirmation authorizes one call, and expires 10 minutes after the server asks.
Org type says nothing about whose data an org holds: a customer sandbox runs with no prompt. --deny-orgs refuses an org outright.
"args": [
"-y",
"@certinia/apex-log-mcp",
"--deny-orgs",
"prod-*-org@mycompany.com,acme--*,type:production"
]An entry matches the org id, username, alias or instance URL. * is a glob, and the match is anchored and ignores case, so prod-*@acme.com denies prod-eu@acme.com and not xprod-eu@acme.com. A deny on any alias of a username holds, whichever name the agent uses. Every value comes from the local sf files, so the server refuses a named org before it connects to it.
An org id matches in its 15- or 18-char form, whatever its case. An instance URL matches by its host, so acme--* denies every sandbox of the acme My Domain.
A type: entry denies a type from the table above, e.g. type:sandbox. type:production also denies an org whose type cannot be read, because the server treats that org as production. The server contacts the org before it refuses on type: it connects, and it queries the org type. No Apex runs and no record is written. A type: entry that names no org type stops the server.
Nothing lifts a deny - not --allow-production-orgs, not a confirmation. The refusal names what matched.
A deny covers every org tool, since a log holds the org's data. --deny-orgs '*' refuses them all, and the analysis tools keep working.
Only the org id is unspoofable. An alias can be re-pointed, so treat the rest as convenience, not a security boundary.
Flag | Description |
| Run against production orgs, and orgs whose type cannot be read, with no confirmation. A |
| Refuse every Apex execution. The tool stays visible, without its parameters, so agents know it exists. Every other tool still works, |
| Refuse every tool that changes an org: |
| Refuse these orgs. See Deny lists. |
To stop Apex running, add the flag to the Quick Start args:
"args": ["-y", "@certinia/apex-log-mcp", "--no-apex-execution"]See the Contributing Guide, Developing to set up your environment, and the Code of Conduct.
BSD 3-Clause. Copyright © Certinia Inc. All rights reserved.
Trace a user, class or trigger in a Salesforce org until the trace flag expires. A user's flag stores each transaction they run as a debug log, which can fill log storage; a class or trigger flag only sets that code's levels. Refused if one of its log type exists. Leaves a debug level in the org.
| Name | Required | Description | Default |
|---|---|---|---|
| targetOrg | No | Alias or username of the target Salesforce org. Uses the project default if not specified. | |
| debugLevel | No | A level for every category, or the named ones over apexlog_execute_anonymous's defaults (default: those) | |
| tracedEntity | Yes | A username or user id, or a class or trigger name (ns.Name if namespaced) | |
| durationMinutes | No | How long it logs (default: 30) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only carry destructiveHint=false, so the description must do the heavy lifting — and it does: it warns that a user flag can fill log storage, explains the different effect for class/trigger flags, discloses the refusal condition, and notes the lingering side effect ('Leaves a debug level in the org'). Missing are reversibility/cleanup instructions and permission requirements, but the disclosure goes well beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the core action before the caveats. Each sentence carries a distinct fact (effect, storage risk, refusal, residue), though 'Refused if one of its log type exists' is grammatically terse enough to be slightly ambiguous.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description never says what is returned (e.g., the flag id or debug level handle) that an agent would need for later cleanup. The mutation's side effects are well covered, but the return contract and the 'one of its log type exists' condition are underspecified for an agent to act deterministically.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all four parameters including the debugLevel unions and duration bounds. The description adds only indirect color ('until the trace flag expires' gesture toward durationMinutes) and no format or syntax details beyond the schema — baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Trace a user, class or trigger') and clarifies the scope ('until the trace flag expires'), which distinguishes it from the read-only siblings like apexlog_get_org_logs. It does not explicitly name any sibling, so the differentiation is implied rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied by the fact that it is the only creation tool among list/get siblings, and the refusal condition ('Refused if one of its log type exists') is a useful gating hint. However, there is no explicit when-to-use guidance, no mention of when to prefer this over tracing via execute_anonymous, and no prerequisite/permission statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute anonymous Apex in a Salesforce org as the targetOrg user; DML commits unless the run fails. Saves the debug log and returns its path for the analysis tools. With no active trace flag, adds one for the run, deleted after, and a debug level, left in the org.
| Name | Required | Description | Default |
|---|---|---|---|
| apex | No | The anonymous Apex to execute, or use apexFilePath | |
| outputDir | No | Log directory (default: .apex-log-mcp/ in the first client root, else cwd) | |
| targetOrg | No | Alias or username of the target Salesforce org. Uses the project default if not specified. | |
| debugLevel | No | This run's log levels. Omit for the user's trace flag levels, else the defaults; "default" forces the defaults; a bare level sets every category; an object sets the named categories over the defaults. Defaults: apexCode, apexProfiling, visualforce, workflow FINE; callout, system, validation DEBUG; database FINEST; nba, wave INFO. | |
| apexFilePath | No | Absolute path to a file of anonymous Apex |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing that DML commits unless the run fails, that a trace flag is auto-created and deleted after the run, and that a debug level is left behind in the org. These side effects are exactly what an agent needs before invoking a destructive, non-idempotent tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action and mutation consequence in the first sentence, with side effects second. The final clause ('adds one for the run, deleted after, and a debug level, left in the org') is slightly compressed and takes a re-read, but no sentence is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers mutation semantics, org side effects, and the return value (log path) despite no output schema. It stops short of describing failure behavior such as compile errors or whether logs are still saved on failure, which matters for a destructive execution tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters like debugLevel, outputDir, and apexFilePath are already fully documented. The description adds only one semantic nugget – that the debug level persists in the org – which is useful but marginal against the schema's own detail, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Execute anonymous Apex in a Salesforce org') plus execution identity ('as the targetOrg user'), which no sibling provides. An agent can distinguish it from apexlog_get_org_logs or apexlog_create_trace_flag 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies the workflow by saying it 'returns its path for the analysis tools,' routing the agent to the summary/search/limit-risk siblings for follow-up. It does not explicitly state when *not* to use it or when to prefer pre-existing logs via apexlog_get_org_logs, so exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download debug logs from a Salesforce org, by id or the newest N, and return each saved file's path, which the analysis tools accept.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Log ids, from apexlog_list_org_logs | |
| latest | No | The newest N logs, in place of ids (default: 1) | |
| outputDir | No | Log directory (default: .apex-log-mcp/ in the first client root, else cwd) | |
| targetOrg | No | Alias or username of the target Salesforce org. Uses the project default if not specified. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description usefully discloses that files are saved locally and their paths are returned for downstream analysis. However, with only destructiveHint=false in annotations, it does not cover overwrite behavior, permissions, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the core action and ends with the most important output detail: saved file paths accepted by analysis tools.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential workflow: download logs and return file paths for analysis. With no output schema, it appropriately explains the return value; minor gaps like overwrite behavior are acceptable given the schema's parameter detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameter meaning is already well documented. The description reinforces the id/latest N selection and output path usage, but adds little beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: download debug logs from a Salesforce org, selectable by id or newest N. It distinguishes itself from the listing sibling by focusing on download and local file paths, though it does not explicitly name the sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used before analysis tools because it returns paths they accept, but it does not explicitly state when to use ids versus latest N or when to choose this over listing logs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a high-level summary of an Apex debug log: how long the transaction ran, where the time went by debug log category and the level each was logged at, every governor limit it and each namespace consumed, whether the log is complete, the exceptions and flow errors it raised, and what ended the transaction if it failed. Best for a quick overview.
| Name | Required | Description | Default |
|---|---|---|---|
| logFilePath | Yes | Absolute path |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the description focuses on content. It meaningfully discloses what the agent will receive, including diagnostic details like governor limit consumption per namespace, log completeness, and the failure cause. It stops short of noting any limitations such as behavior on truncated/incomplete logs or path errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the verb and resource, then a tight enumeration where each item adds real information about the output. The list is long but not padded; only the trailing 'Best for a quick overview' is slightly soft.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must stand in for the return shape, and it does so thoroughly across time breakdown, limits, completeness, and errors. Only minor gaps remain, such as expected log state or failure behavior on an unreadable path.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single parameter with 100% schema description coverage ('Absolute path'), so the schema already carries the burden. The description adds nothing about the path format, expected file type, or consequences of an invalid path, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get a high-level summary of an Apex debug log') and enumerates exactly what the summary contains: duration, category breakdown, governor limits, completeness, exceptions/flow errors, and termination cause. That scope clearly separates it from sibling log tools like apexlog_search_events or apexlog_list_org_logs, though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Best for a quick overview' implies when to reach for it, but no alternative is named and no condition for when NOT to use it is given (e.g., when you need raw event-level detail, use apexlog_search_events). Usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the governor limits an Apex log transaction has nearly used up - CPU time, heap, SOQL queries and rows, SOSL queries, DML statements and rows, callouts and every other limit - worst first, with how much of each was used
| Name | Required | Description | Default |
|---|---|---|---|
| threshold | No | Minimum usedPercentage to report (default: 80) | |
| logFilePath | Yes | Absolute path |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: results are ordered 'worst first' and each entry reports how much of the limit was used, which tells the agent what the output looks like without an output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler. The long limit enumeration is slightly run-on but earns its place by clarifying the scope of 'every other limit' and the 'worst first' ordering.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read-only analysis tool with full schema coverage and no output schema, the description supplies the key missing piece: what the results contain and their ordering. Minor gaps remain around error behavior for an unparseable or missing log file, but nothing blocks correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented (threshold default 80, absolute logFilePath path). The description's 'nearly used up' framing loosely reinforces the threshold concept but adds no new format or semantics; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List the governor limits an Apex log transaction has nearly used up') and enumerates the covered limits, so an agent knows exactly what analysis it performs. It does not explicitly name how it differs from siblings like apexlog_get_summary or apexlog_list_slow_operations, leaving that differentiation to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the phrase 'nearly used up' and the threshold parameter; there is no explicit statement of when to reach for this tool versus apexlog_get_summary or apexlog_list_slow_operations. No exclusions or prerequisites (e.g., that the log must be retrieved first) are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the debug logs stored in a Salesforce org, with how many match. Pass ids to apexlog_get_org_logs to download them.
| Name | Required | Description | Default |
|---|---|---|---|
| user | No | Username whose activity was logged | |
| limit | No | Page size (default: 20) | |
| cursor | No | nextCursor from the previous page | |
| sortBy | No | Descending (default: startTime) | |
| request | No | e.g. "Api" or "Application" | |
| operation | No | Part of the operation, any case, e.g. "aura" for /aura | |
| succeeded | No | false for failed logs only | |
| targetOrg | No | Alias or username of the target Salesforce org. Uses the project default if not specified. | |
| startTimeTo | No | ||
| startTimeFrom | No | ISO 8601 with a zone, e.g. 2026-10-09T09:00:00Z | |
| minFileSizeBytes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that results include a match count, but says nothing about pagination behavior, default page size, or how the cursor interacts with the 200 cap — gaps that matter for an 11-parameter listing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero filler; the enumeration purpose comes first and the follow-up download step second, matching the natural call order.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 11 optional filter parameters and no output schema, the description covers the core intent and the downstream handoff but omits what the returned entries look like, how the count is expressed, and any pagination semantics an agent needs to page correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 82%, so the schema already documents nearly every parameter including enums and time formats. The description adds no filtering syntax, default, or interaction guidance beyond the schema, which is the expected baseline when coverage is this high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("List the debug logs stored in a Salesforce org") plus an output trait ("with how many match"), and explicitly names the sibling apexlog_get_org_logs as the download step, so the agent can distinguish the two without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear workflow cue: use this to enumerate and then pass ids to apexlog_get_org_logs to download. It does not, however, mention when to prefer the other list/search siblings (apexlog_list_slow_operations, apexlog_list_limit_risks, apexlog_search_events), leaving that routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank what an Apex debug log spent its time on by self-execution time, or on the heap it retains - code units, methods, queries, searches, DML, callouts, flows and workflows in one table, each row with its calls, durations, database counts and rows, so the caller can see what to optimize and why, beside the query optimizer's plan for the queries among them.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Rank only these log event types, e.g. SOQL_EXECUTE_BEGIN, DML_BEGIN, METHOD_ENTRY | |
| limit | No | Page size (default: 10); fewer if the page would be too large | |
| offset | No | Ranked rows to skip (default: 0): the last page's nextOffset | |
| sortBy | No | Default durationSelfMs. heapSelfNetBytes adds that column. | |
| groupBy | No | Fold repeats into one row; default name. callerNamespace attributes platform DML to the package that drove it. debugCategory folds a namespace's event types together and so states no type or name. none ranks each call on its own. A grouped durationTotalMs is what the transaction takes back if the group never runs - never sum it across rows. | |
| minSelfMs | No | Drop operations below this self time (default: 0), whichever sortBy is used | |
| namespace | No | Rank only these namespaces | |
| logFilePath | Yes | Absolute path | |
| debugCategory | No | Rank only these debug log categories |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds output-shape behavior not in the annotations: a single ranked table whose rows carry calls, durations, database counts and rows, plus the query optimizer plan alongside queries. It does not itself mention pagination or the grouped-duration-summing caveat (those live in schema parameter text), so it stops short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded sentence that leads with the ranking purpose and then the row contents; it is dense but every clause carries information (ranking axes, covered types, row columns, optimizer plan). It runs long and could be split into two sentences for scanability, which keeps it off a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully compensates by describing the returned table and its columns. Given 9 parameters at 100% schema coverage, the remaining param detail is adequately handled elsewhere. The main gap is that paging behavior and the grouped-duration summing rule are only discoverable by reading parameter descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, including enum values, defaults, and even the non-additive durationTotalMs warning, so the schema does the semantic heavy lifting. The description only implicitly maps to sortBy ('by self-execution time, or on the heap it retains') and says nothing about grouping, paging, or filtering parameters. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (rank) plus resource (Apex debug log operations) and the two ranking bases (self-execution time, retained heap). It also enumerates the covered event types (code units, methods, queries, DML, callouts, flows, workflows), so an agent knows exactly what population is ranked. It does not name or contrast with siblings like apexlog_get_summary or apexlog_search_events, leaving that inference to the agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: 'so the caller can see what to optimize and why' signals the performance-tuning scenario but gives no explicit when-to-use or when-not-to-use criteria. No alternative tool is named, so an agent must decide on its own between this, apexlog_get_summary, and apexlog_search_events.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the events of an Apex debug log in log order: what the code printed (USER_DEBUG), validation rules, statements, or every event under one method. For plain text in the saved .log, grep is cheaper; use this for event types, nesting, or without a shell. Text past 400 characters is elided; ask for one event by eventIndex to read up to 30,000.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Only these log event types, e.g. USER_DEBUG, VALIDATION_RULE | |
| limit | No | Page size (default: 50) | |
| offset | No | Rows to skip (default: 0): the last page's nextOffset | |
| contains | No | Only events whose text holds this, ignoring case | |
| namespace | No | Only these namespaces | |
| eventIndex | No | Only this event, with more of its text | |
| logFilePath | Yes | Absolute path | |
| parentEventIndex | No | Only events below this one |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover readOnly/openWorld; the description adds the behavior that matters — results come in log order, text beyond 400 characters is elided, and a single-event fetch by eventIndex returns up to 30,000 characters. That truncation-and-workaround disclosure is exactly the kind of trait an agent cannot infer from structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, no filler: purpose first, alternative second, truncation caveat last. Every clause carries information an agent needs to pick or invoke the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter read tool with no output schema, the description covers selection, ordering, and truncation. It never sketches the returned row shape or how paging terminates; the schema mentions nextOffset, but the description would have been the place to connect it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so 3 is the baseline, but the description adds real semantics beyond the schema: eventIndex is characterized as the way to defeat elision, and the paging model implied by ordinal results is at least gestured at. It does not explain limit/offset interaction or nextOffset explicitly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb and resource ('Search the events of an Apex debug log in log order') plus concrete examples of what counts as an event (USER_DEBUG, validation rules, statements, per-method nesting). It differentiates against grep but never mentions any sibling MCP tool such as apexlog_get_summary or apexlog_get_org_logs, so the differentiation is incomplete rather than absent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit when-not ('for plain text in the saved .log, grep is cheaper') and the conditions that select this tool instead ('event types, nesting, or without a shell'). It also routes within the tool itself: use eventIndex when you need the elided text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.0.2apexlog_create_trace_flagapexlog_execute_anonymous5 fields changedInput schema / properties / apex / descriptionPrevious value: -"The anonymous Apex to be executed"New value: +"The anonymous Apex to execute, or use apexFilePath"Input schema / properties / apexFilePathAdded value: +{
+ "description": "Absolute path to a file of anonymous Apex",
+ "type": "string"
+}Input schema / properties / debugLevel / descriptionPrevious value: -"Trace flag log levels. \"default\" restores the defaults; a bare level sets every category to it; an object sets only the categories named and leaves the rest unchanged. Defaults: apexCode, apexProfiling, visualforce, workflow FINE; callout, system, validation DEBUG; database FINEST; nba, wave INFO."New value: +"This run's log levels. Omit for the user's trace flag levels, else the defaults; \"default\" forces the defaults; a bare level sets every category; an object sets the named categories over the defaults. Defaults: apexCode, apexProfiling, visualforce, workflow FINE; callout, system, validation DEBUG; database FINEST; nba, wave INFO."Input schema / properties / outputDir / descriptionPrevious value: -"Directory to save the debug log file. Defaults to .apex-log-mcp/ in the project root."New value: +"Log directory (default: .apex-log-mcp/ in the first client root, else cwd)"Input schema / requiredRemoved value: -[
- "apex"
-]apexlog_get_org_logsapexlog_list_limit_risks1 field changedInput schema / properties / threshold / descriptionPrevious value: -"Report a limit once it is this percentage consumed (default: 80)"New value: +"Minimum usedPercentage to report (default: 80)"apexlog_list_org_logsapexlog_list_slow_operations1 field changedInput schema / properties / offset / descriptionPrevious value: -"Ranked rows to skip (default: 0). Advance it by the rows you got, which can be fewer than limit."New value: +"Ranked rows to skip (default: 0): the last page's nextOffset"apexlog_search_eventsv2.0.1analyze_apex_log_performanceapexlog_execute_anonymousapexlog_get_summaryapexlog_list_limit_risksapexlog_list_slow_operationsfind_performance_bottlenecksget_apex_log_summaryv1.0.0analyze_apex_log_performancefind_performance_bottlenecksget_apex_log_summaryScored across 8 tools
The tools are mostly clearly separated by resource and action: listing versus downloading org logs are distinct, and the analysis tools each target a different view of a log. Some overlap remains between get_summary, list_slow_operations, list_limit_risks, and search_events, since all analyze the same log artifact, but their descriptions make the intended use cases reasonably clear.
Every tool uses the same apexlog_ prefix followed by a consistent snake_case verb_noun pattern, such as apexlog_get_org_logs, apexlog_list_slow_operations, and apexlog_search_events. The naming is predictable throughout.
Eight tools is well scoped for an Apex log retrieval and analysis server. Each tool covers a distinct part of the workflow: obtaining logs, executing Apex, creating trace flags, and analyzing different aspects of a log.
The surface covers the core lifecycle well: listing and downloading logs, producing logs via anonymous Apex or trace flags, and several rich analysis views. Minor gaps exist around explicit trace-flag cleanup or log deletion, but agents can work around these with the available operations.
The Polar Signals MCP server enables AI assistants to connect directly with performance profiling data, allowing users to analyze application performance through natural language queries. Key capabilities include querying CPU performance and memory usage, exploring profiling metadata like profile types and labels, and providing AI-driven code optimization suggestions directly within development environments like Claude Code or Cursor.
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for Sentry - error monitoring, issue tracking, and debugging for AI assistants
Analytics and debugging for your MCP server — explore usage and sessions, then root-cause errors.
