The orgintel server is a read-only Salesforce permission architecture analysis tool that snapshots org permissions into a local DuckDB store to support RBAC remediation. It provides the following capabilities:
Snapshot org: Bulk-fetch the entire permission model (profiles, permission sets, groups) into a local store; returns summary stats only.
Manage snapshots: List existing snapshots with org info, timestamps, and row counts.
Describe objects: Get a live field list for any Salesforce object with a sensitivity guess per field, with sensitive fields ordered first.
Run read-only SOQL queries: Execute SELECT-only queries with a hard row cap and automatic redaction of identifier columns.
Analyze profiles: View profiles sorted by user count, including license, permission cardinality, and ModifyAllData flag.
Compare permissions: Compute the symmetric difference between two principals' permissions, grouping differing fields by permission signature.
Find sensitive access: Identify principals granting read/edit on fields matching sensitivity patterns, with affected user counts resolved through effective permissions.
Verify decomposition: Formally check whether a proposed base-profile + permission-set decomposition preserves every user's effective permissions exactly.
Propose decomposition: Automatically compute a thin-base profile and permission-set decomposition (via Jaccard clustering), then verify and return it with placeholder keys for naming and justification.
Provides tools for analyzing Salesforce permission architecture, including profiles, permission sets, and permission set groups, to support RBAC remediation. Capabilities include snapshotting permission models, diffing permissions, detecting sensitive field access, verifying and proposing permission decompositions.
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., "@orgintel snapshot my sandbox and show me profiles with sensitive field access"
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.
An MCP server that analyzes Salesforce permission architecture — profiles, permission sets, and permission set groups — to support RBAC remediation. It reads an org, snapshots the permission model into a local DuckDB store, and answers questions about it. Phases 1–4 (acquisition, analysis core, eval harness, agent).
Two hard guarantees, both enforced as mechanism rather than policy:
Read-only. orgintel never issues an insert, update, delete, or metadata deploy
against any org. Enforced by a transport-layer route allowlist (see
clients/transport.py); a non-allowlisted
request raises before it is sent.
No personal identifiers persisted. The users table has no name, username, or
email column — the columns do not exist. soql_query masks identifier columns in its
results. See DESIGN-P1.md §2.7.
A mid-size org has ~850k FieldPermissions rows — a raw dump is ~20M tokens, ~100× a
context window. The model never sees raw API output. Every tool returns an
aggregate, a diff, or a bounded slice; the join happens in DuckDB. Every response
carries a budget that discloses truncation and how to narrow.
Related MCP server: KubeGuard MCP Server
Requires uv and the Salesforce CLI (sf).
uv sync
uv run pytest # 51 tests, no org neededorgintel reads the access token from an org you've already authenticated with the Salesforce CLI — zero extra setup. JWT bearer flow is a planned seam, not yet built.
sf org login web --alias my-org # once
sf org list # confirm it's ConnectedThe subprocess argv is fixed and its output (which contains a live token) is never logged.
Tool | What it returns |
| Bulk-fetches the permission model into DuckDB. Returns summary stats only — counts, timing, snapshot_id. |
| Available snapshots, newest first. |
| Profiles by user count: license, perm cardinality, ModifyAllData flag, unassigned count. |
| Live field list with a |
| Symmetric difference of two principals. Differing fields grouped by |
| Read-only SOQL. SELECT-only parser guard, row cap, identifier columns redacted. |
| (P2) Every principal granting read/edit on a name-matched sensitive field, with affected user counts resolved through effective permissions. Recall-first. |
| (P2) Formal check that a proposed base-profile + permission-set/group refactor leaves every user's effective permissions unchanged. Returns per-user added/removed grants; an uncovered user fails. |
| (P4) Computes a thin-base + permission-set decomposition (deterministic) and runs it through |
scope defaults to all tables. Apex in SetupEntityAccess is excluded by default
(84% of that table, ~noise for RBAC); pass "setup_entity_access:apex" to include it.
Two P2 functions — effective_permissions (union across profile + permission sets + PSG
components, minus muting) and cluster_profiles (Jaccard clustering of profiles) — are
internal building blocks, not yet exposed as tools. verify_decomposition is the crown
jewel: permission-refactor correctness is formally checkable, so "did the refactor
preserve access" is a boolean, not a judgement call — and propose_decomposition is
gated by it, so an unverifiable proposal is never returned.
agent/ is an MCP client that drives these tools via the Anthropic API
(claude-opus-5). The division of labor is the whole point: the tools compute and
verify; the model orchestrates, names, and judges. propose_decomposition returns a
verified structure with placeholder names; the model names each base in the customer's
vocabulary and writes the rationale. The model also judges whether an unmatched field
name looks sensitive (mbr_num__c, dob_enc__c) — the gap P3 measured as evasive recall.
uv sync --extra agent
orgintel-agent "snapshot <orgalias>, then propose a decomposition" # billableThe model call sits behind an LLM protocol, so the loop, tool bridge, and judge are all
tested with a scripted fake — no API key, no billing. Only orgintel-agent makes real
calls. uv run python -m evals.agent_delta measures the evasive-recall lift the judge
buys (0.0 → 1.0 with the offline stand-in; detectable recall held at 1.0).
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"orgintel": {
"command": "uv",
"args": ["run", "orgintel"],
"cwd": "../MCP Salesforce"
}
}
}Then in Claude: "Snapshot my-org, then show me the profiles with the most users, then diff the top two."
The highest-signal artifact in the project: a scoreboard for the deterministic analysis core, built before the agent so it develops against numbers, not vibes.
uv run python -m evals.run # writes evals/REPORT.md + a run to evals/history/fixtures/generate.py synthesizes org snapshots with planted ground truth
(deterministic given a seed): latent roles, redundant pairs that should collapse,
adversarial "do not consolidate" cases, and sensitive fields — some pattern-detectable,
some named to evade (mbr_num__c, dob_enc__c). The harness scores cluster purity,
sensitive-field recall (detectable target 1.0; evasive recall is the gap the P4 model
must close, measured explicitly), and privilege preservation (verify_decomposition must
certify a ground-truth decomposition and catch a broken one). Each run diffs against the
previous, so a prompt or pattern change that drops recall shows up immediately.
One DuckDB file, default ~/.orgintel/snapshots.db, override with ORGINTEL_DB. Set it
per client engagement to keep each org's data in its own file. A snapshot holds
principal/object/field metadata and pseudonymous user ids — re-identification
requires authenticated access to the source org. Snapshot files are git-ignored.
src/orgintel/
clients/ thin async SF wrappers (REST, Bulk 2.0, SFDX auth) — no DB, guarded transport
store/ DuckDB schema (SQL migrations), ingest, queries, snapshot loader — no network
analysis/ pure functions: diff, effective perms, clustering, sensitivity, verify, propose — no I/O
agent/ MCP client + Anthropic-backed model (LLM protocol), tool loop, field judge
config/ sensitivity.yaml (patterns + setup-entity scope)
snapshot.py the acquisition coordinator (auth -> fetch -> ingest)
server.py nine FastMCP tools — thin
fixtures/ deterministic synthetic orgs with planted ground truth (P3)
evals/ scoreboard: run.py (deterministic core) + agent_delta.py (P4 model lift)See DESIGN-P1.md for the schema rationale and CLAUDE.md for conventions.
Live describe of an object's fields with a sensitivity_guess flag per field (SSN/DOB/account-number/etc from config). Sensitive fields ordered first.
| Name | Required | Description | Default |
|---|---|---|---|
| api_name | Yes | ||
| org_alias | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and discloses that fields are ordered with sensitive ones first and include a sensitivity_guess flag. However, it could mention that it is a read-only operation and any 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?
The description is concise with two sentences, front-loading the key action ('live describe') and including important detail about sensitive fields ordering. It could be slightly more structured, but remains efficient.
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?
Despite having an output schema (not shown), the description adequately explains the return value (fields with sensitivity flags). However, with 2 undocumented parameters and no schema coverage, the description is incomplete regarding input semantics.
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?
The description does not explain the parameters api_name and org_alias beyond their types and titles. Since schema coverage is 0%, the description should add meaning, such as the format or source of api_name and the role of org_alias.
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?
The description clearly states the tool provides a 'live describe' of object fields with a sensitivity flag per field, and distinguishes it from siblings like soql_query by focusing on metadata rather than data.
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 for viewing field metadata with sensitivity clues, but lacks explicit guidance on when to use it vs alternatives like find_sensitive_access, and does not mention prerequisites or constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every principal granting read/edit on a field whose name matches a sensitivity pattern (SSN/DOB/account-number/card/comp/… from config), with how many users end up with that access (resolved through effective permissions, honoring muting). Recall is prioritized over precision — expect broad matches.
| Name | Required | Description | Default |
|---|---|---|---|
| snapshot_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description effectively discloses key behaviors: effective permissions honoring muting, recall over precision, and broad matches. It implies a read-only query without stating explicitly, but the traits are well-described.
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 concise sentences cover the core purpose and a key behavioral trait. No extraneous text, though the parameter omission could be addressed with a brief addition.
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?
Given the complexity of sensitive access detection and the presence of an output schema (not shown), the description adequately explains the input, matching logic, and output scope. Missing only parameter details, but overall complete.
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 0% and the description does not mention the single required parameter 'snapshot_id', failing to explain its role or how to obtain it. This is a significant gap since the parameter is essential.
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?
The description clearly states the tool finds every principal granting read/edit on fields matching sensitivity patterns (SSN/DOB/account-number/card/comp), distinguishing it from siblings like permission_diff which handle general permission differences.
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 provides clear context for use: to detect sensitive access with recall prioritized over precision. It does not explicitly mention when not to use or alternatives, but the context is sufficient for most agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Profiles in a snapshot: name, license, user count, perm cardinality, and whether they hold ModifyAllData. Sorted by user count desc. Unassigned profiles surfaced.
| Name | Required | Description | Default |
|---|---|---|---|
| snapshot_id | Yes | ||
| include_user_counts | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description discloses sorting (by user count desc) and that unassigned profiles are included. However, no annotations exist, and the description does not mention side effects, permissions, or error conditions. Adequate but incomplete.
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, each adding value (output fields, ordering, edge case). No redundant or missing words; front-loaded with key information.
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?
Given 2 parameters, output schema exists, and no nested objects, description covers input, output, ordering, and an edge case (unassigned profiles). Minor gap: error handling or required snapshot validity not addressed.
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 0%, but description adds context: output includes 'user count' which relates to include_user_counts param. Snapshot_id is implied but not explained. Partial compensation for missing schema descriptions.
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?
Description clearly states verb ('list') and resource ('Profiles in a snapshot') with specific output fields (name, license, user count, perm cardinality, ModifyAllData). Distinguishes from siblings like snapshot_org or permission_diff by focusing on profile listing.
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?
No explicit guidance on when to use this tool versus alternatives (e.g., describe_object, permission_diff). Context implies use for profile overview but lacks when-not or sibling comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available snapshots (newest first) with org, timestamp, and row counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavior fully. It correctly implies a read-only list operation and details ordering and returned fields. No side effects are mentioned, but none are expected.
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?
The description is a single sentence that efficiently conveys the tool's purpose and key details without any unnecessary words.
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 simple listing tool with no parameters and an output schema, the description is sufficient. It specifies ordering and returned fields, which covers the essential information needed by an agent.
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 are no parameters, so the description does not need to add parameter information. Baseline score of 4 is appropriate for zero-parameter tools.
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?
The description clearly states the tool lists snapshots with ordering (newest first) and specifies included fields (org, timestamp, row counts). This is specific and distinguishes it from sibling tools like snapshot_org.
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?
While there is no explicit when-not-to-use or alternatives, the description provides clear context for a straightforward listing operation. The lack of parameters simplifies usage, making the purpose obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Symmetric difference of permissions between two principals (profile or permission set). Differing fields grouped by (a_perm, b_perm) signature. The P1 workhorse.
PSGs are out of scope in P1 (they need union-minus-muting resolution — P2's
effective_permissions); passing one returns an instructive error, not a wrong answer.
| Name | Required | Description | Default |
|---|---|---|---|
| principal_a | Yes | ||
| principal_b | Yes | ||
| snapshot_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It discloses that PSGs return an instructive error and that results are grouped by signature. However, it does not mention whether the operation is read-only, performance characteristics, or error handling for invalid inputs.
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?
The description is three sentences, front-loaded with the purpose, then providing detail and exclusion. Every sentence adds value without redundancy or unnecessary text.
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?
Given the three parameters and existence of an output schema, the description explains the return format (grouped by signature) and the PSG error behavior. However, it does not cover all potential errors or the structure of the output in detail, making it moderately complete.
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?
With 0% schema coverage, the description should compensate. It only hints that principals can be profile or permission set and does not explain the format of principal_a, principal_b, or snapshot_id. The description adds minimal parameter insight 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?
The description clearly states that the tool computes the symmetric difference of permissions between two principals (profile or permission set) and groups them by signature. It specifies it is the P1 workhorse, distinguishing it from sibling tools like find_sensitive_access.
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 explicitly excludes PSGs, stating they require P2's effective_permissions tool, providing clear when-not-to-use guidance and an alternative. It labels the tool as the P1 workhorse, implying it is the default for permission diffing in P1.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Propose a thin-base-profile + permission-set decomposition. The STRUCTURE is computed deterministically (cluster the profiles, derive each cluster's shared base and each profile's deviation) and is run through verify_decomposition before it is returned — if it doesn't preserve every user's effective permissions, you get the failure, not the proposal. Names and rationale are deliberately NOT provided: the tool returns placeholder keys plus each base's member profile names and shared grants as raw material for YOU to name in the customer's vocabulary and justify.
| Name | Required | Description | Default |
|---|---|---|---|
| threshold | No | ||
| snapshot_id | Yes | ||
| target_base_count | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the proposal is run through verify_decomposition before returning and that names/rationale are deliberately omitted. This adds useful behavioral context beyond the 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?
The description is a single paragraph of 4 sentences, front-loaded with the main purpose. It is concise and avoids redundancy, though a structured format (e.g., bullet points) could improve readability.
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?
Given the presence of an output schema, the description does not need to detail return values. It mentions placeholder keys and raw materials but lacks parameter semantics. The description is adequate for a proposal tool but has gaps.
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 0%, meaning the description does not explain any of the 3 parameters (snapshot_id, threshold, target_base_count). The description focuses on the overall function but leaves the meaning and usage of parameters entirely to the schema, which is inadequate.
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?
The description clearly states it proposes a 'thin-base-profile + permission-set decomposition', specifying the verb 'Propose' and the resource. It distinguishes from siblings like verify_decomposition and list_profiles by describing its deterministic computation and integration with verification.
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 usage for generating a decomposition proposal, but does not explicitly state when to use this tool versus alternatives like verify_decomposition or list_profiles. No when-not or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bulk-fetch a Salesforce org's permission architecture into the local snapshot store. Returns ONLY summary statistics — never permission rows. scope defaults to all tables; pass 'setup_entity_access:apex' to include Apex (off by default).
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | ||
| org_alias | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it returns only summary statistics and never permission rows, and explains the scope default. However, it lacks details on other behaviors such as whether the snapshot store is overwritten or appended, authentication requirements, or rate limits, which are not covered by 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?
The description is very concise with two sentences: the first states the purpose, and the second clarifies the scope behavior. No unnecessary words, and key information is front-loaded.
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?
Given the tool's complexity (bulk-fetch with potential impact), the description is adequate but could be more complete. It does not mention return value details (output schema exists but is not described) or behavior regarding existing snapshots, but it covers the main purpose.
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?
With 0% schema description coverage, the description adds meaningful context for the scope parameter (defaults and format) beyond the schema. The org_alias parameter is not further explained, so not all parameters are fully clarified, but the main parameter benefits.
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?
The description clearly states the tool bulk-fetches permission architecture into a snapshot store, using a specific verb and resource. It distinguishes from siblings by noting it returns only summary statistics, not permission rows, but does not explicitly name sibling tools.
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 provides guidance on the scope parameter default and how to include Apex, but does not explicitly state when to use this tool versus sibling tools like permission_diff or list_snapshots. Usage context is implied but not fully delineated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read-only SOQL. SELECT-only (parser-guarded), hard row cap, identifier columns (Name/Email/Phone/...) redacted before results are returned (DESIGN §2.7).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| max_rows | No | ||
| org_alias | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden. It discloses read-only nature, SELECT-only parser guarding, hard row cap, and identifier column redaction—key behavioral traits beyond the input 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?
Two sentences, no fluff. Front-loaded with the core purpose ('Read-only SOQL'), and each subsequent clause adds unique behavioral detail. Highly efficient.
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?
Given the output schema exists and parameters are moderate, the description covers the essential restrictions and privacy behavior. It lacks explicit mention of the org_alias parameter's role, but overall is sufficient.
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 0%, and the description does not explain individual parameters (query, max_rows, org_alias). It only indirectly hints at max_rows via 'hard row cap', providing minimal added meaning.
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?
The description clearly states 'Read-only SOQL' and 'SELECT-only', specifying the verb (query) and resource (SOQL). It distinguishes from sibling tools like describe_object by emphasizing data querying with constraints.
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 use for reading data via SOQL but does not explicitly provide when-to-use or when-not-to-use guidance relative to sibling tools, nor does it mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Formal check: does a proposed base-profile + permission-set/group decomposition leave EVERY user's effective permission set unchanged? Returns per-user added/removed grants (both must be empty to pass) and any users the plan fails to cover. This is a boolean, not a vibe — it either preserves privilege exactly or it doesn't.
| Name | Required | Description | Default |
|---|---|---|---|
| proposal | Yes | ||
| snapshot_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool returns per-user added/removed grants and any uncovered users, with both grants needing to be empty to pass. Since no annotations are provided, the description carries full burden and does so well, though it could mention whether it modifies state (it doesn't).
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?
The description consists of two clear, front-loaded sentences with no wasted words. Every sentence adds value: the first explains purpose and output, the second emphasizes the boolean nature.
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 mentions return values (added/removed grants, uncovered users) but omits details on the complex 'proposal' parameter structure and required 'snapshot_id'. Given the output schema exists, return details are less critical, but parameter guidance is lacking.
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?
The description does not explain the two parameters ('snapshot_id' and 'proposal') beyond what the schema shows. Given 0% schema description coverage, the description should compensate but fails to provide any parameter meaning or constraints.
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?
The description clearly states the tool's purpose: verifying that a proposed base-profile + permission-set/group decomposition leaves every user's effective permission set unchanged. It specifies the exact verb ('verify') and resource ('decomposition'), and distinguishes from siblings like 'propose_decomposition' and 'permission_diff'.
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 when to use: for a formal, exact check of privilege preservation. It contrasts with a 'vibe', indicating rigorous use. However, it does not explicitly list when not to use or name alternative tools for proposing or diffing permissions.
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.
v0.1.0describe_objectfind_sensitive_accesslist_profileslist_snapshotspermission_diffpropose_decompositionsnapshot_orgsoql_queryverify_decompositionScored across 9 tools
Each tool targets a distinct operation: snapshots, listing, describing, querying, profiling, diffing, sensitive access search, and decomposition verification/proposal. No overlap in functionality.
All tools follow a consistent verb_noun snake_case pattern (e.g., snapshot_org, list_snapshots, permission_diff), making the purpose clear from the name.
9 tools is well-scoped for the domain of Salesforce org permission analysis and decomposition. Each tool serves a clear role without redundancy.
The toolset covers the entire workflow: fetching permission architecture, describing objects, querying, listing profiles, diffing permissions, finding sensitive access, and proposing/verifying decompositions. No obvious gaps.
IaC attack-path auditor: finds internet-to-crown-jewel chains in Terraform/CFN/K8s.
Cloud cost, inventory and governance on AWS/Azure/GCP. Read-only by default, optional scoped writes
Identity and authorization in one system: allow, deny, the reason, and a record.
CloudOracle - 14-tool multi-cloud compliance MCP: AWS, Azure, GCP posture, IAM, configs.
