Cirra AI Salesforce Admin MCP Server

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

Annotations declare destructive/openWorld, and the description adds real context on top: 90-second wait ceiling with a resumable jobId, the fact that CSV uploads bypass the model, that hardDelete skips the Recycle Bin and needs a specific permission, and that CSV jobs return an upload URL instead of a Salesforce job. No annotation is contradicted.

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?

Lead sentence states the operation surface, second routes away from the sibling, third explains the two upload modes, fourth explains the timeout/jobId lifecycle. Every sentence carries distinct information with no restatement of the schema.

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 11-parameter, zero-required, destructive job-orchestration tool this covers the essentials an agent must know to act correctly: when to use it, how to start a job, how to wait or abort, and the async failure mode. An output schema exists, so return-shape detail is not required.

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 baseline is 3; the description still earns above that by explaining the records/recordIds/jobId interaction — jobId causes records to be ignored, and recordIds take precedence for deletes. It does not touch pageSize or the connection-selection params, which is acceptable given the schema documents them.

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?

Names the exact verb set (insert/update/upsert/delete/hardDelete) and resource (large Salesforce record sets) plus the mechanism (Bulk API 2.0 ingest jobs). It is immediately distinguishable from the single-record siblings sobject_dml/sobject_create/sobject_update.

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?

Explicitly routes the agent: 'Use this instead of sobject_dml when processing more than ~200 records,' with a concrete threshold. It also disambiguates the two invocation modes — pass records/recordIds for inline upload, omit them to open a CSV job.

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

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

Goes well beyond annotations (readOnly/idempotent/openWorld/destructive=false) by disclosing the 90-second wait behavior and the async escape hatch: a returned jobId can be passed back to wait or abort. This is exactly the operational 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?

Four short sentences: purpose, routing rule, unsupported constructs, async behavior. Front-loaded and every sentence carries decision-relevant information with no 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?

Output schema exists, so return values needn't be explained, and annotations cover the safety profile; the description still adds the timeout/jobId continuation model. It is slightly thin on the multi-team connection flow (context_handle / cirra_ai_team), though the schema descriptions handle that fully.

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 baseline is 3; the description earns a bump because it explains why jobId is returned (timeout) and that it can be reused to wait or abort, tying the two-phase workflow together in a way the per-parameter schema text does not. It does not cover the connection/team routing params, but those are fully documented in 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 (run a large Salesforce SOQL query) plus the underlying mechanism (Bulk API 2.0 query jobs). It explicitly contrasts with the sibling soql_query, so an agent can select between them 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 an explicit routing rule: use this instead of soql_query when expecting thousands of rows or when a REST query times out. It also lists when-not (no GROUP BY, aggregates, OFFSET, TYPEOF, parent-to-child subqueries), leaving little to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds one genuine behavioral fact beyond that: the call returns instructions the agent must read before proceeding. It does not mention that the tool can be refused when multiple teams/connections exist without a context_handle — a refusal behavior that lives only in the parameter 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, the imperative call-order requirement front-loaded with emphasis, and the must-read-the-response note immediately after. Nothing is wasted, though the second sentence is a meta-instruction rather than information about the tool itself.

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?

An output schema exists and the parameter schema is fully documented, so the description does not need to explain return values or arguments. What remains missing is a one-clause statement of what this call establishes (team + Salesforce connection context), which would make the mandatory sequencing self-explanatory rather than something the agent must infer from the schema.

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%, and the scope/sf_user/cirra_ai_team/context_handle semantics are documented in detail there, including the enum behavior and the refusal condition. The description adds nothing about parameters, which is acceptable at full coverage but earns no credit above baseline.

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 establishes that this is a mandatory initialization step, and the name plus title make 'initialize session for Cirra AI' clear enough to distinguish it from every sibling (all of which are Salesforce operations). However, it never says what initialization actually establishes — the team and Salesforce connection — leaving that entirely to the schema, so the stated purpose is ordering-only rather than substantive.

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?

'Call cirra_ai_init before calling any other tools of the Cirra AI MCP server' is unambiguous sequencing guidance, which for a bootstrap tool is the most important when-to-use signal. It does not need to name an alternative since none exists, but it also gives no guidance on repeat calls or when to re-initialize mid-conversation (that is only implied by the schema's context_handle text).

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is largely covered. The description still adds useful scope boundaries (enhanced workspaces only, not legacy) and the fact that authoring and delivery surfaces are split. It does not itself flag that publish/unpublish changes what site visitors see or that delete requires an unpublished variant first, though those details do appear in the parameter schemas.

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, front-loaded with purpose then routing, with zero filler. The long capability enumeration partially restates the operation enum already in the schema, which keeps it from 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?

For a 21-operation, 11-parameter tool with an output schema and rich annotations, the description covers scope, sibling routing, and the enhanced-vs-legacy split. Workflow preconditions (variant-level edits, unpublish before delete, approval gating) are documented in the schema rather than the description, so the description alone is not fully self-sufficient but nothing critical is absent from the definition as a whole.

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% and the parameter descriptions are unusually detailed (variantId lifecycle, contentKeyOrId body placement, body field caveats). The tool description adds no parameter-level meaning of its own, so the baseline of 3 applies when structured fields carry the load.

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 set and resource (author/manage Salesforce CMS content in enhanced CMS workspaces) and enumerates the concrete capabilities: content and variants, publish/unpublish, taxonomy terms, spaces, folders, channels. It explicitly distinguishes itself from the two nearest siblings, cms_delivery for published-channel reads and connect_rest for uncovered CMS resources, so an agent can pick it 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?

Gives explicit routing conditions: use cms_delivery to read content already published to a channel or Experience Cloud site, use connect_rest for digital asset management providers, search indexing, folder sharing, and legacy CMS workspaces. The exclusions cover exactly the areas an agent might wrongly assume this tool handles.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond them: it returns only content already published to a channel, so drafts are invisible, and it is channel-scoped. It does not discuss pagination ceilings or result sizes, but those are partly covered in the schema and 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?

Two sentences, front-loaded with the verb and resource, then the operation inventory, then the routing/exclusion sentence. No filler, and the most decision-relevant information (published-only, use cms_content for authoring) lands before the reader stops.

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 an output schema present, return-value documentation is unnecessary; annotations cover safety; and the schema covers all 9 params at full coverage. The description supplies the remaining pieces an agent needs — scope, published-only constraint, sibling disambiguation, and entry point via list_channels.

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 the search POST-only/queryTerm requirement, the list_contents query params, and the warning that delivery channel IDs differ from authoring channel IDs, so the baseline is 3. The DESCRIPTION text itself adds nothing about parameters, so no credit above baseline.

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 ('Read published Salesforce CMS content through delivery channels') and then enumerates the concrete operations: list channels, list/get/search content, get collection items. It explicitly distinguishes itself from the sibling cms_content, so an agent can choose 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?

Names the alternative (cms_content) and the exact conditions that select it: authoring, publishing, and inspecting unpublished drafts. It also gives a starting point ('Start with list_channels' is echoed in the operation param) and makes the published-only restriction explicit, which is precisely the routing information an agent needs.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the description's added value is scope and access semantics: paths must come verbatim from the Connect REST reference and DevOps resources follow the connection's DevOps access category rather than metadata access. It does not itself restate the destructive/mutating risk or rate-limit behavior, but that is covered by annotations and the method param.

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 core capability, then scope, then exclusions; no filler sentences. It is dense and long-ish, but every sentence carries routing or constraint information an agent needs for a generic passthrough API 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?

With an output schema present and full annotation coverage, the description supplies exactly the missing pieces: what surface is reachable, what isn't, path sourcing rules, and sibling alternatives. Nothing needed to invoke it correctly is absent.

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 baseline is 3; the description adds real meaning beyond the schema by warning that paths must be taken from Salesforce's reference and not guessed, and that an empty path returns the Connect directory for the context user. It also implicitly constrains what belongs in path versus queryParams.

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 ('Call any Salesforce Connect REST API resource under /services/data/vXX.X/connect/') and enumerates the resource families covered (Core, CMS, Experience Cloud, Files, Personalization, Commerce, DevOps). It also explicitly disambiguates from siblings (cms_content, cms_delivery, soql_query, sobject_dml, tooling_api_*, metadata_*), so an agent can pick it 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?

Gives explicit when-to-use (Connect REST resources), when-not-to-use (Chatter under /chatter/ is not reachable; use soql_query/sobject_dml/tooling_api_*/metadata_* for other APIs), and preference routing ('prefer cms_content and cms_delivery when they cover the operation'). The empty-path behavior for discovery is also spelled out.

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

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

Annotations already cover read-only/idempotent safety, and the description adds the key behavioral trait they can't express: this call consumes context window budget, which is why the artifact URL is preferred. It doesn't mention cursor expiry or failure behavior, keeping it below 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?

Three short sentences, front-loaded with what it does, then how to use it, then the caution. Every sentence carries distinct, actionable 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?

Output schema exists and parameters are fully described, so the description only needs to add the context-cost warning and cursor provenance, both of which it does. Minor gap: no note on what happens with an expired or invalid cursor.

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 all four parameters, including their origins (artifactAccess.artifactId, _pagination.nextCursor, cirra_ai_init context_handle), are already documented. The description restates the cursor source but adds nothing new about parameters.

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: 'Fetch the next page of a large tool response.' It is unambiguous and no sibling tool covers pagination, so confusion risk is low, though it doesn't name a specific alternative 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?

Gives a clear trigger ('Use the nextCursor from _pagination in a previous response') and points to a preferred alternative ('prefer the artifact download URL when available'). It lacks an explicit 'do not call when...' case, but the routing signal is strong.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so safety is covered structurally. The only added behavioral detail is the word 'public', which is thin; it says nothing about failure modes, duplicate-name behavior, or what happens to a 'role' that the API may reject.

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 short sentence, front-loaded with the verb and resource, with no padding. It is under-specified rather than bloated, which is the conciseness dimension's only real weakness here.

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?

An output schema exists so return values need not be explained, but this is a 9-parameter mutation with a required auth/context flow that the description never mentions. An agent reading only the description would not know it must supply context_handle or cirra_ai_team+sf_user to avoid a refused call.

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 baseline is 3 and the schema already explains name, type, label, description, supportedObjects and the connection parameters. The description adds nothing about parameters and its mention of 'role' conflicts slightly with the two-value type enum.

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 (create a group/queue) in Salesforce, which is clear on its own. It doesn't differentiate from siblings like group_update or group_members, and it adds 'role' which the type enum (Regular/Queue) does not allow.

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 guidance on when to use this versus group_update, group_members, or permission-set tooling. Nothing tells the agent about prerequisites such as needing a context_handle from cirra_ai_init, which the schema says is effectively mandatory.

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

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

Annotations already disclose destructiveHint=true, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond restating the operation: it doesn't say whether removes are reversible, whether partial failures are rolled back across multiple groups/users, or that this is a bulk membership mutation.

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 scope qualifier follows the verb/resource immediately.

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?

An output schema exists and annotations cover the safety profile, so much is carried by structured data. However, for a destructive, non-idempotent bulk membership mutation, the description omits any note on multi-user/multi-group blast radius or partial-failure behavior.

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% and the operation enum is documented inline, so the schema carries parameter meaning. The description adds no syntax hints (e.g. how names vs IDs resolve) beyond what the schema already states.

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 two specific verbs (add/remove) against a precisely scoped resource set (users from public groups, queues, or roles in Salesforce). This clearly separates it from group_create and group_update, which manage the groups themselves rather than membership.

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?

There is no guidance on when to choose this versus permission_set_assignments, user_update, or group_update, and no stated preconditions. Usage is only inferable from the verb itself.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds no behavioral context beyond the resource type: it does not explain what properties are updatable, whether updates are partial, how membership is affected, or what permissions are required.

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 front-loaded sentence with no wasted text. It is concise, though that concision also leaves important update semantics unaddressed.

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 mutation tool with a nested 'properties' object that allows arbitrary keys, the description does not explain what can be updated or how updates behave. Even accounting for rich schema descriptions, annotations, and an output schema, the definition is materially incomplete for 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 the input schema already documents group, sf_user, cirra_ai_team, and context_handle. The description adds no parameter-level meaning beyond the schema, which matches the baseline of 3 when the schema carries documentation.

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 states a clear verb and resource: 'Update a public group or queue in Salesforce.' It lets an agent tell this apart from creation tools like group_create at a basic level, but it does not explicitly differentiate from sibling tools such as group_members or group_create.

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 gives no explicit guidance on when to use this tool versus alternatives such as group_create or group_members. It implies usage through 'Update' but provides no prerequisites, exclusions, or routing logic.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered structurally. The description adds nothing beyond that — no indication of what a returned link looks like, whether it is a URL string or an object, or how incomplete setupConfig affects the result.

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 tight sentences with the purpose front-loaded and no filler. The second sentence is somewhat imperative/redundant with the first but still earns its place as a routing rule.

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 an output schema and rich annotations, the description needn't explain return values or safety. However, for a tool with a nested setupConfig object and connection-selection parameters, it says nothing about the fact that a useful link requires specifying an artifact type and name, leaving the agent to infer this entirely from the schema.

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% and the nested setupConfig fields (type, sObjectNameOrId, artifactNameOrId) are individually documented, so the baseline of 3 applies. The description mentions no parameter at all, not even the required type='setup' or how setupConfig changes the output link.

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: 'Build Salesforce links for setup pages.' An agent can immediately tell this generates URLs rather than manipulating metadata. No sibling tool produces links, so differentiation is implicit 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?

'Always use this tool when user requests a setup page link' gives a clear triggering condition. It lacks anything on when not to use it or on what happens if setupConfig is omitted, but the positive routing rule is unambiguous.

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

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

With annotations present the bar is lower, but the description does not disclose any consequence of logging out — whether credentials are invalidated, whether subsequent tool calls fail, or whether a reconnect is required. Given idempotentHint=false and readOnlyHint=true, an agent would benefit from knowing the session state changes and that calling twice is not harmless.

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 clause with no filler, front-loaded and easy to scan. However, its brevity comes at the cost of all behavioral and follow-up context, so it is under-specified rather than optimally concise.

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?

An output schema exists, so return values need not be explained, but for a session-terminating operation the description omits the critical postcondition: what stops working after logout and how to reconnect (cirra_ai_init is a sibling). That gap is material to correct agent behavior.

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 tool takes zero parameters and the schema is trivially empty, so there is nothing for the description to disambiguate. Baseline 4 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 ('Logout') and resource ('Cirra AI MCP server'), which is unambiguous and clearly distinct from every sibling tool. It stops short of 5 only because it merely restates the annotation title with no additional scope detail.

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 guidance on when to call this versus simply ending the session, no mention of what must happen afterward (e.g., re-run cirra_ai_init to reconnect), and no prerequisites. The agent must infer all usage context.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, openWorldHint=true, non-idempotent, non-destructive), so the description needn't restate safety. It adds nothing about batch semantics though — e.g. whether a failure on one element aborts the whole call, what error shape comes back, or whether created elements are validated/activated before deploy.

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, zero filler. The positive scope comes first and the exclusion/routing constraint second, which is the right front-loading for a create 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?

With a full schema, an output schema, and mutation annotations already present, the description covers purpose and the one critical sibling disambiguation. The only remaining gap is batch/partial-failure behavior for multi-element creation, which the schema does not express.

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 all five parameters (type, sf_user, metadata, cirra_ai_team, context_handle) are already documented, and the baseline of 3 applies. The description's examples of metadata types weakly clarify the `type` parameter but add no syntax or accepted-value detail 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 ('Create one or more Salesforce metadata elements') and grounds it with concrete examples (validation rules, custom labels, page layouts), so the agent knows exactly what class of objects this operates on. It also names a sibling it is not for (CustomField / sobject_field_create), sharpening the boundary.

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?

Explicitly states a when-not condition: 'Do not use for CustomField' and routes to `sobject_field_create` with the reason (Field-Level Security granted automatically). This is exactly the alternative-routing an agent needs to avoid a wrong tool pick.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is largely covered. The description usefully adds the hard 10-per-batch ceiling, but it never mentions that metadata deletions are irreversible, whether any dependency protection exists, or what permissions are required for a destructive operation on a live org.

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, front-loaded with the action and scope, then the batch ceiling in caps for emphasis. Nothing here 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?

An output schema exists so return values need no explanation, and annotations cover the safety flags. However, for a destructive bulk-delete on production metadata, the omission of reversibility, failure/dependency behavior, and permission requirements leaves a meaningful gap.

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 baseline would be 3, but the description adds real meaning for the 'type' parameter by naming concrete metadata types, which the schema leaves as a bare 'The metadata type.' It also reinforces the fullNames cap that the schema expresses as maxItems: 10, though it adds nothing about the connection/context_handle parameters.

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?

A precise verb ('Delete') plus a scoped resource ('Salesforce metadata elements of a specified type'), with concrete examples (custom fields, validation rules, custom labels). The destructive verb cleanly separates it from metadata_create, metadata_update, metadata_read, and metadata_list in the sibling set.

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 never says when to reach for this tool versus metadata_update or the Tooling API DML alternatives, nor does it state prerequisites or what to do when a deletion fails or is blocked by dependencies. The only guidance given is a batch-size cap, which is a constraint rather than a use-case rule.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile needs no restating. The description adds that results are scoped to the connected org and hints at what the verbose payload contains, but says nothing about paging, cost, or the very different payload sizes between verbose true and false.

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 the resource first and illustrative properties after; no filler, no repetition of schema content.

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 a fully documented 5-parameter schema, an output schema, and annotations covering safety, the description only needs to establish purpose and it does. The remaining gap is disambiguation from metadata_list, which matters here because the two names are nearly interchangeable to 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?

Schema description coverage is 100% and every parameter (sf_user, verbose, pageSize, cirra_ai_team, context_handle) is well documented inline, including the required context_handle/cirra_ai_team pairing rule. The description adds no parameter meaning beyond the schema, so the 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 ('List') plus specific resource ('Salesforce metadata types available in the org') and even the shape of returned properties (directory name, suffix, child objects). It stops short of differentiating itself from the near-identically named sibling metadata_list, leaving the agent to guess which of the two enumerates types versus components.

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?

There is no statement of when to use this versus metadata_list, metadata_read, or tooling_api_describe, and no prerequisites or exclusions. The only usage-shaped information (the verbose toggle) lives in the schema, not the description.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that — no note on pagination behavior, result volume, or permission requirements — though the schema covers pagination.

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 well-formed sentence with the core action front-loaded and the optional scoping clause trailing. No wasted 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?

With an output schema present, rich annotations, and fully documented parameters, the description covers what the tool does adequately. The only gap is the lack of routing guidance among the many metadata_* siblings.

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 all six parameters are already documented in the schema, including the folder scoping and connection/context parameters. The description only echoes the type and folder semantics, adding no new 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?

States a specific verb (List) and resource (Salesforce metadata elements) and gives concrete examples of types (flows, custom objects, reports). It does not explicitly distinguish itself from siblings like metadata_describe or metadata_read, which an agent would need to disambiguate.

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 phrase 'optionally scoped by folder' implies when the folder parameter applies, but there is no explicit guidance on when to choose this tool over metadata_describe, metadata_read, or tooling_api_describe. 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.

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds no behavior beyond that—nothing about pagination, partner/child recursion, or connection requirements (those live only in the schema's parameter descriptions).

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 concrete examples and no filler. It is efficient, though the examples consume space that could have gone to sibling differentiation.

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?

Output schema and 100% parameter coverage mean the description does not need to explain returns or inputs, and the annotations carry the safety profile. What remains missing is the routing information an agent needs to pick this over the other metadata_* tools.

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 schema_description_coverage at 100%, the schema fully documents all seven parameters, including the rich format/cirra_ai_team/context_handle semantics. The description only echoes 'specified type' and 'one or more' elements, so 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 (read full details for metadata elements of a specified type) and grounds it with concrete examples such as flows, validation rules, and approval processes. It does not, however, distinguish itself from siblings like metadata_describe or metadata_list, which read similar 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 never says when to choose this over metadata_list (listing) or metadata_describe (describing shape). The closest it comes is 'full details', leaving the agent to infer the boundary from sibling names alone.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false; the description goes well beyond by disclosing REPLACE SEMANTICS for ApprovalProcess, Layout, Flow, StandardValueSet and GlobalValueSet — omitted children are removed — and by explaining that `patch` avoids that data loss. That is the single most consequential behavior for this tool and it is stated plainly rather than left to discovery.

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?

It is dense but front-loaded: purpose first, then the two modes, then the destructive replace warning. The closing clause ('Using `patch` avoids this because the diff is applied to the current object') restates a point already made earlier in the paragraph, which is the one avoidable redundancy.

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 mutating tool with an output schema, the description covers mode selection, the destructive replace behavior for composite types, and the recovery workflow. Minor gaps remain — nothing about permissions or how partial failures across multiple `metadata` records are reported — but nothing essential to invoking it correctly is missing.

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 carries the field-level detail (including the JSON Patch element structure and the identity-vs-index path rules). The description still adds decision-level semantics absent from the schema: which of `metadata` vs `patch` to supply, and that `fullName` pairs with `patch` while being ignored with `metadata`.

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 opens with a specific verb and resource ('Update one or more Salesforce metadata elements of a specified type') and immediately names concrete element types (flows, validation rules, custom labels). It also defines two distinct invocation modes, which lets an agent distinguish this tool from metadata_create/read/delete without opening a 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?

It explicitly routes the agent between alternatives: mode (1) `metadata` for full objects, mode (2) `patch` for a large single record such as a Flow because 'you do not have to resend the whole object'. It further states a prerequisite workflow ('metadata_read first, merge your change, and send the full payload') for composite types, which is exactly the when-and-how guidance an agent needs.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true; the description adds nothing beyond restating that it clones. It says nothing about whether the source layout is modified, what happens if newLayoutName collides, or that a new layout artifact is created in the org.

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. It is efficiently written, though its brevity is also the source of the missing guidance rather than a deliberate trade-off.

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 an output schema present and full schema coverage, the description needn't explain returns or parameters. However, for a 7-parameter mutation tool with non-idempotent semantics and multiple connection-routing options, it should at least flag the create-and-name behavior and call out the sibling page_layout_update.

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 every parameter is documented in the schema, including the layout-ID-vs-name branching and connection/context_handle rules. The description contributes no parameter meaning beyond the schema, 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?

It states a specific verb ('Create ... by cloning') and resource ('page layout in Salesforce'), so the operation is unambiguous. It does not differentiate from the sibling page_layout_update, which an agent must infer from names alone.

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?

There is no guidance on when to use this versus page_layout_update or metadata_create. The only implicit signal is 'cloning', which the agent must interpret on its own. No prerequisites or preconditions are mentioned.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true; the description adds genuinely new context by revealing that rename is implemented 'via clone and delete', which explains the destructive flag and warns that the layout gets replaced. It says nothing about required permissions or side effects on dependent record types, but with annotations covering the safety profile this is a solid contribution.

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 tight sentences, no filler, with the core verb and resource front-loaded in the first clause and the mode options immediately following. Every sentence earns its place.

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?

An output schema exists and annotations carry the behavioral profile, so the description does not need to explain return values or safety. It covers the two mutation paths adequately; only cross-tool routing and prerequisites for name-based lookup are left implicit elsewhere.

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 every parameter including the context_handle/cirra_ai_team connection selectors is already documented in the schema. The description's 'patch, newLayoutName, or both' restates the schema constraint rather than adding syntax or format detail, so the 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 ('Update or rename a page layout in Salesforce') and enumerates the two supported mutation modes. It does not explicitly differentiate from close siblings such as page_layout_clone or metadata_update, so an agent still has to infer which tool applies.

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 by listing the two modes (JSON Patch content edit, rename, or both), but gives no when-to-use/when-not guidance and never points to alternatives like page_layout_clone for duplicating a layout or metadata_update for other metadata. Usage must be inferred from mode capability alone.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered elsewhere. The description adds nothing beyond that — no mention that removals can strip user access, whether batch operations are atomic, or what happens when a permission set is already assigned.

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 tight sentence with no waste and the operation front-loaded. It is not padded, though it is so short that brevity costs it useful detail rather than earning 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?

An output schema exists, so return values need no explanation, and the schema covers connection and context parameters. Still, for a destructive write tool with duplicate-assignment and bulk-behavior questions left open, the description is only minimally adequate.

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 all six parameters (users, permissionSets, operation, sf_user, cirra_ai_team, context_handle) are already documented in the schema. The description adds no extra semantics, which is acceptable at this coverage level.

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?

Clear verb plus resource ('assign or remove permission sets from users') and it implicitly separates the assignment concern from permission_set_update, which edits permission sets themselves. It never names that sibling, so differentiation has to be inferred.

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 dual add/remove purpose is implied, but there is no guidance on when to use this versus permission_set_update, profile_update, or user_update, and no preconditions (e.g. permission set must exist) are stated.

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

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

The description goes beyond stating it is a write operation (covered by annotations) and specifies the *nature* of the update—modifying properties, contents, and object/field access—which is crucial behavioral context for the payload construction.

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?

It is a concise, single-sentence description that is highly focused and efficiently communicated front-loaded with the core function.

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 rich input schema and helpful annotations (destructiveHint: false, idempotentHint: true), the description provides a complete high-level summary of the tool's function and its modification capabilities.

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 100% schema description coverage, the description provides the necessary high-level summary of the operation without adding significant unique semantic value beyond what is defined in the schema's intent for the 'patch' array.

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 uses a specific verb ('Update') and clearly defines the resource (Permission Set) and the scope of modification (properties, contents, read/edit access). This is highly distinct from related tools like permission_set_assignments.

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 it doesn't explicitly list when NOT to use this tool, it provides a clear scope of what the tool can modify, guiding the agent's understanding of its capabilities relative to other general update functions.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the agent knows this is a non-idempotent write against a live org. The description adds nothing beyond that: it does not say whether all permissions/settings are copied, whether an existing target name causes an error, or that the effect is not reversible via this 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?

A single front-loaded sentence with no filler, which is structurally sound. It is arguably too thin for a cloning mutation, but there is no wasted 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?

An output schema exists so return values need not be described, but for a mutation that creates new metadata in a Salesforce org the description omits required behavior: that a new profile is created, whether permissions and settings are copied, and how name collisions are handled.

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 the parameters are documented and the baseline is 3. The description adds no meaning, and notably does not resolve the schema's apparently swapped semantics ('profile' described as 'the name of the new Profile' while 'clonedProfileName' is 'existing Profile which will be cloned').

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 states a specific verb and resource ('Clone ... profile in Salesforce'), which is clear enough to act on. It does not distinguish this from siblings like page_layout_clone or profile_update, and 'user profile' could momentarily suggest the User object rather than the Profile metadata type.

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?

There is no guidance on when to use clone versus profile_update (duplicate an existing profile vs change one) or page_layout_clone (a different object entirely). No prerequisites are stated, such as the source profile needing to exist or name-uniqueness constraints.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. Beyond that, the description adds nothing: no warning that omitting narrowing parameters on standard profiles can produce a very large payload, no note that a context_handle or team+user pair is required to resolve the connection, and no hint about the returned structure despite a rich 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 short sentence with no padding, but it is under-specified rather than tightly economical — the space available is unused rather than well-spent. Nothing is front-loaded beyond the bare purpose.

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 heavy lifting is delegated: annotations cover safety, the output schema covers return values, and all six parameters are fully documented in-schema. That makes the definition callable, but for a tool whose response size varies enormously and whose connection resolution has explicit refusal conditions, the one-line description is thinner than ideal.

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 for permissionTypes, so the schema carries essentially all parameter meaning. The description contributes no additional syntax or format guidance, which lands this at the baseline for fully documented schemas.

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 ("Return detailed metadata for a Salesforce Profile"), which is clearly distinct from write-oriented siblings like profile_update, profile_clone, and permission_set_update. It does not, however, position itself against read siblings such as sobject_describe or permission_set_assignments, which also surface permission 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?

There is no when-to-use or when-not-to-use guidance. The description never tells the agent to prefer this over sobject_describe for object-level permissions, nor does it explain that permissionTypes and sObject are required and narrow the response — that guidance exists only inside the schema.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, but the description adds real behavioral context beyond them: it identifies the concrete settings mutated and explains the login IP range semantics as an allowlist that blocks users from any other address, plus the requirement for explicit confirmation before adding the first range. It stops short of stating required permissions ('Manage Profiles') or whether a multi-element JSON Patch applies atomically.

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, both load-bearing: the first states scope with concrete examples, the second routes the agent away to the correct sibling. No restatement of the tool name, no filler, and the alternative-tool routing is front-loaded where the agent can act on it.

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 mutation tool with rich annotations, an output schema and 100% parameter coverage, the description covers what it changes, which sibling handles adjacent cases, and the highest-risk side effect with its confirmation gate. The gaps are minor: authentication/permission prerequisites for updating profiles and the behavior on partial patch failure are unstated.

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 all six parameters, including the JSON Patch format for 'patch' and the connection-selection logic, are already documented. The description contributes only indirect guidance by enumerating which profile aspects can be patched, which helps an agent construct the patch but adds little the schema does not already contain. Baseline 3 applies when the schema carries the parameter burden.

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 (Update) and resource (Salesforce user profile) and enumerates the concrete settings in scope: record type visibility, page layout assignments, login IP ranges, system permissions, description. It also explicitly carves out the object/field/tab-permission territory to sobject_dml, so an agent can distinguish it from sibling tools without opening a 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?

Explicitly names the alternative and the condition that selects it: 'For object, field and tab access, use sobject_dml on the profile's ObjectPermissions, FieldPermissions or PermissionSetTabSetting records instead.' The confirmLoginIpRestriction schema entry further states when to set the flag ('only after the user has explicitly confirmed') and points to the org-wide Network Access trusted IP ranges as the non-restrictive alternative.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond the verb 'Create'—it does not mention permission requirements, duplicate-name handling, side effects on profiles/layouts, or what happens when required parameters conflict.

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 front-loaded sentence with no wasted words. It is efficient, though arguably too sparse for a 15-parameter creation 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?

The tool has 15 parameters with 10 required, nested array structures, and meaningful business concepts such as business processes and profile availability overrides. Given this complexity, the one-line description is not complete enough—it omits when to use the tool, prerequisites, and any behavioral caveats, even though the annotations and output schema cover safety and return values.

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 all 15 parameters, including nested availabilityOverrides and layoutAssignmentOverrides, are fully documented in the schema. The description adds no parameter semantics beyond what the schema provides, which is the baseline expectation when coverage is 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?

The description uses a specific verb and resource: 'Create a new sObject record type in Salesforce.' It is clearly a creation operation, but it does not explicitly differentiate itself from the sibling record_type_update, leaving the agent to infer the distinction from the verb alone.

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?

There is no explicit guidance on when to use this tool versus record_type_update, metadata_create, or other creation tools, and no prerequisites or exclusion conditions are stated. The usage is only implied by the name and verb.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true and openWorldHint=true, so safety is covered. The description only adds that the tool can activate/deactivate a record type, and says nothing about the real behavioral risk: a record type change ripples into profile availability and layout assignments, and the schema marks 11 fields required even for a simple deactivate.

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. It is efficient, though at 15 parameters and 11 required fields the brevity borders on under-specification rather than tight editing.

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 15-parameter mutation with 11 required fields, the description omits the critical fact that all required fields must be supplied even when only toggling active or renaming. An output schema exists so return values need not be explained, but the calling contract for this wide required-parameter surface is not conveyed.

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 every parameter is documented in the schema, including the context_handle and cirra_ai_team connection-selection fields. The description adds no parameter-level meaning of its own, 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?

The description names a specific verb (update, plus activate/deactivate) and a specific resource (sObject record type in Salesforce), so the operation is unambiguous. It does not distinguish itself from close siblings such as record_type_create or metadata_update, leaving the agent to infer the boundary from names alone.

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?

There is no guidance on when to use this versus record_type_create, metadata_update, or page_layout_update, and no mention of prerequisites or context requirements. The agent must infer usage entirely from the tool name and schema.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that results are returned and filters/format can be overridden, but says nothing about pagination behavior (a real concern given pageSize and maxRecords) or the connection/context selection requirement.

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 that names the action, the identifier, the output, and the optional knobs. Nothing is redundant or buried.

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?

An output schema exists, so return values needn't be explained. However, for a tool with 8 parameters, nested objects, and a connection-selection rule where a call with neither context_handle nor cirra_ai_team + sf_user is refused, the description omits that prerequisite and the pagination semantics entirely.

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 the schema already documents all 8 parameters including the nested reportFilters and reportFormat. The description only echoes "optional filters and format overrides" and adds no syntax, defaults, or semantics beyond what the schema provides.

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 a Salesforce report by ID and return its results," plus the scope of optional filters and format overrides. An agent can distinguish this from the query siblings (soql_query, bulk_query) by the saved-report framing, 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?

There is no explicit when-to-use guidance and no alternatives are named, even though soql_query, bulk_query, and tooling_api_query sit in the same family. The agent must infer that this is for pre-built reports rather than ad-hoc queries.

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

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

Annotations already declare non-readonly, non-destructive, non-idempotent, open-world. The description adds the crucial behavioral facts annotations can't convey: execution is asynchronous and the call returns a job ID for polling rather than results. It falls short of naming the polling mechanism or noting prerequisites such as deployed code.

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, zero filler, and the most decision-relevant fact (async, returns a job ID) leads. The mode selection rule follows immediately and every sentence earns its place.

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?

Explains the async execution model, the returned job ID, and the two selection modes, and an output schema exists so return values need not be described. The remaining gap is what the agent should do with the job ID — the description never points to the polling 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?

Schema description coverage is 100%, so every parameter is already documented, including enum values and the tests/testLevel incompatibility. The description only restates that same split at a high level without adding format or syntax detail beyond the schema, 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 ('Run Apex tests and native Flow Tests'), plus the key behavioral trait (asynchronously, returns a job ID). No sibling in the list does test execution, so the tool is unambiguously distinguishable 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?

Explicitly frames the two mutually exclusive modes: 'tests' to name specific classes/methods, or 'testLevel' to run org-wide. It does not name any alternative tool (e.g. which tool polls the returned job ID), but within the tool the selection guidance is clear.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and non-idempotent, so the safety profile is known. The description adds the auth/session prerequisite from cirra_ai_init, which is real value, but it never says that destructive risk is concentrated in the 'remove' action while 'list'/'describe' are harmless reads — an agent could over-apply caution or under-apply it.

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, front-loaded sentences with no filler; the prerequisite is easy to spot. It is efficient but so terse that the efficiency shades into under-specification for a five-action 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 a tool tagged destructive with five heterogeneous actions spanning read (list/describe) and mutation (add/remove/reauthenticate), the description says almost nothing about behavior differences. An output schema exists so return values need no explanation, but the action-level behavior gap remains substantial.

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% and the action enum carries per-value semantics, including what 'describe' returns, so the schema does the heavy lifting. The description contributes nothing about action selection, sf_user defaulting, or the context_handle vs cirra_ai_team requirement, 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?

The verb is the vague umbrella "Manage" and the resource is "connections to Salesforce orgs," which is on-target but non-specific. The five distinct capabilities (list, describe, add, remove, reauthenticate) live only in the action enum, so the description itself does not let an agent distinguish scope from siblings like logout or cirra_ai_init.

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 only guidance is a prerequisite: "Call cirra_ai_init at least once before using this tool," which is useful ordering information. There is no when-to-use or when-not guidance per action, and no routing away from siblings such as logout or cirra_ai_init when the intent is ambiguous.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false and openWorld=true, so the safety profile is covered. The description adds nothing beyond that: it doesn't say the change is an irreversible org metadata mutation, what permissions are required, or how name-conflicts on an existing sObject behave.

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. It is efficiently structured, though brevity here shades into under-specification given the tool's complexity.

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 18-parameter, 6-required org-mutating tool, the description omits the connection/context selection requirement, the fact that it creates metadata rather than data, and any caveats about naming or rollback. The output schema covers returns, but the call prerequisites an agent must satisfy are absent.

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 the schema already documents all 18 parameters including the tricky context_handle/cirra_ai_team interaction. The description only echoes three field groups (sharing model, deployment status, config options) without adding syntax or defaulting guidance, so it sits at the baseline.

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 ('Create a new custom object (sObject) in Salesforce') plus the main configuration axes. It is clear what the tool does, but it does not distinguish itself from nearby siblings like metadata_create or sobject_field_create, which plausibly also create org metadata.

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?

There is no guidance on when to use this versus metadata_create or sobject_field_create, no prerequisites (permissions, connected org), and no mention that the required context_handle/cirra_ai_team connection selection must be supplied — a call with neither is refused.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds only a light statement of what comes back (fields, relationships, record types), which the output schema also covers; it says nothing about permissions required, depth of metadata, or whether field-level security affects results.

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 trailing clause enumerating fields, relationships and record types is mildly redundant with the output schema, keeping it just below 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?

The tool is simple, the schema is fully documented and an output schema exists, so the essentials are present. What is missing is disambiguation from the many sibling describe/list tools, which matters given this tool set's density.

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% and each parameter (sObject, sf_user, cirra_ai_team, context_handle) is documented in detail, including the connection-selection rules. The description adds no parameter meaning beyond 'the specified sObject', so the baseline 3 for high-coverage schemas 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 (Return) and resource (metadata for the specified sObject) plus the contents of the result: fields, relationships and record types. That is clear enough to act on, but it never differentiates itself from near-neighbours like metadata_describe, tooling_api_describe, sobjects_list or profile_describe, so an agent must infer which describe-family tool to use.

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?

There is no when-to-use or when-not-to-use guidance and no named alternative. With 40+ siblings including several other 'describe' tools, the description leaves the routing decision entirely to inference from the tool name.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, openWorldHint=true and non-idempotency, so the safety profile is covered structurally. The description adds one genuinely useful behavioral constraint — the ~200-record threshold implying partial-failure/perf limits — but says nothing about allOrNone semantics, partial success handling, or the permission-before-execute requirement that matters for a destructive 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 sentences, zero filler, with the core capability first and the routing constraint immediately after. Nothing redundant with the name or annotations.

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 an output schema, full annotations, and 100% schema coverage, the description only needs to cover routing and scope, which it largely does. The remaining gap is disambiguation from the dedicated sobject_create/sobject_update/tooling_api_dml siblings in a very crowded namespace.

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% and every parameter including records/recordIds/upsert's externalIdField and the context_handle gating is documented in-schema, so baseline is 3. The description contributes no additional parameter semantics beyond restating the operation types.

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 set (create, update, delete, upsert) and resource (Salesforce sObject records) via DML, which is clear and actionable. However, it never addresses the overlapping siblings sobject_create and sobject_update, so an agent cannot tell from the description alone whether to use this multi-purpose tool or the dedicated per-operation ones.

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, quantified routing rule: use bulk_dml for more than ~200 records. That is a concrete when-to-use-else condition. But it gives no guidance relative to sobject_create/sobject_update or tooling_api_dml, and no prerequisites (though the safety gate lives in the schema's operation description, not here).

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