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

Annotations already communicate that this is a mutating, non-idempotent write operation (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds the scoping detail that creating a record requires prior schema discovery, which is useful. However, it does not disclose potential side effects such as triggering workflows, required permissions, or duplicate-check behavior, but the annotations cover the core safety profile.

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 two sentences: the first states the core action, the second gives a critical prerequisite workflow. Every clause earns its place, and the guidance is front-loaded before the advisory sentence. No filler or redundant restatement of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter tool with full schema coverage and annotations indicating mutating behavior, the description provides the essential missing context: how to correctly determine payload fields. It also routes the agent to a sibling tool, describe_object, which closes the main knowledge gap. It could briefly mention that responses include the new record ID, but the absence of an output schema reduces that burden.

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%, and both parameters include clear descriptions with examples (object API name and field-values map). The description adds the workflow context of needing required fields and valid picklists, which complements rather than duplicates the schema. It does not need to restate parameter meanings because the schema already carries 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?

The description opens with a specific verb-resource pair ('Create a new Salesforce record'), immediately distinguishing this tool from siblings like get_record, update_record, and delete_record. It also names the exact API domain (Salesforce) and pairs with a supporting sibling, describe_object, so an agent can tell what this tool is for at a glance.

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

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

The description explicitly instructs the agent to call describe_object first to determine required fields and valid picklist values. This is a concrete, actionable usage guideline that prevents errors and clearly differentiates the workflow from simply guessing at field names. It also implicitly warns that this is a create operation, not an update or upsert.

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 mark the tool as destructive, and the description adds meaningful context: the deletion is permanent and user confirmation must precede execution. This goes beyond the structured annotations by specifying the required confirmation workflow.

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 no filler: the first states the core action and permanence, the second gives the essential safety condition. The most important information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive three-parameter tool, the description, annotations, and schema together cover the operation, required confirmation, parameter formats, and irreversibility. No output schema exists, but explaining a delete return value is not essential 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 coverage is 100%, and the schema already documents each parameter in detail, including the confirm requirement and the need to show the user the exact record. The description mostly restates the confirm policy rather than adding new parameter-level meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('delete'), names the resource ('Salesforce record'), and adds the critical qualifier 'permanently'. This clearly distinguishes it from the sibling tools create_record, update_record, get_record, and search_records.

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 explicit operational guidance: confirm=true is required and user approval must be obtained before proceeding. It doesn't explicitly name alternatives, but the delete intent is self-evident and the confirmation gate is the key usage condition.

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 and idempotentHint=true, so the safety profile is covered. The description adds useful output context (field metadata, picklist values) but does not disclose additional behavioral traits such as auth requirements, rate limits, or edge-case behavior.

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 core action and output are front-loaded, and the usage guidance follows immediately. Every word 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?

For a simple read-only metadata tool with only two parameters and no output schema, the description covers the essential behavior and use case. It could be slightly richer by noting the basic vs. full detail distinction, but the schema already documents that.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both object_type and detail are already well documented. The description does not need to compensate, and it adds no significant parameter-level 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?

The description names a specific verb ('Get') and resource ('a Salesforce object's fields') and even enumerates what is returned: API names, types, required flags, and picklist values. It clearly distinguishes this metadata-description tool from record-focused siblings like get_record or run_soql_query.

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 second sentence gives explicit guidance: 'Use before writing SOQL or creating/updating records.' This tells an agent when the tool is appropriate, though it does not explicitly name alternatives or state when not to use it.

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 and idempotentHint. The description adds concrete payload details (user, org id/name/type, instance URL, API version), which is useful behavioral context beyond the annotations. No contradiction or missing critical traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler: the first states exactly what is returned, the second gives the invocation order. Every phrase 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?

For a zero-parameter read-only info tool, the description fully specifies the returned content and the recommended call order. No output schema exists, but the description enumerates the fields, making the tool fully actionable.

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 has zero parameters and schema description coverage is 100%, so no parameter explanation is needed. Per the baseline for zero parameters, this scores well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description explicitly enumerates the returned data: current Salesforce user, org id/name/type, instance URL, and API version. This is a specific, distinct purpose and clearly separates get_org_info from the sibling CRUD/query tools.

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

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

It explicitly directs the agent to 'Call this first to establish context,' providing a clear when-to-use instruction. It does not name exclusions or alternatives, but no sibling tool overlaps with org-level metadata, so the guidance is sufficient.

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 annotations already declare readOnlyHint and idempotentHint, and the description adds no behavioral context beyond the basic fetch operation. It does not mention error handling, missing-record behavior, field-level security, or authentication considerations, and no additional context is provided beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no filler, front-loading the core action and target resource. It is easy to skim and every word contributes to understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, read-only lookup tool with fully documented parameters and safe-operation annotations, the description is mostly sufficient. However, since there is no output schema, it does not clarify the return shape or error behavior, and it relies on the agent to infer usage relative to sibling 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?

Schema description coverage is 100%, so the schema already explains record_id, object_type, and fields clearly. The description adds no parameter-level detail, so the baseline score of 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?

The description uses a specific verb ('Fetch') and identifies the exact resource ('single Salesforce record by Id'), clearly distinguishing a direct-ID lookup from sibling query/search/list tools. It is unambiguous and immediately actionable.

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 when an agent already has a record Id and needs a single record, but it does not explicitly state when to prefer this tool over run_soql_query or search_records, nor does it mention exclusions or alternatives. This is adequate implied guidance, not explicit routing.

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 and idempotentHint=true, so the safety profile is covered. The description adds meaningful behavioral context by naming the excluded system object categories (Share/History/Feed/ChangeEvent tables, non-queryable objects) and the default include_system=false behavior.

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 two sentences with no filler. The core action and output are front-loaded in the first sentence, and the second sentence adds a valuable default-behavior caveat without 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 a simple read-only list tool with two optional parameters and no output schema, the description is nearly complete: it states return fields and default filtering. It could slightly improve by pointing to describe_object for detailed metadata, but this is not a significant gap given the tool's simplicity and annotation coverage.

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 both parameters. The description reinforces that filtering is case-insensitive substring matching and that system objects are excluded by default, but it does not add significant new parameter-level meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and resource ('the org's Salesforce objects') and clearly states the output fields (API name and label). This distinguishes it from siblings like run_soql_query, describe_object, and get_org_info without needing to open their schemas.

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 makes the tool's scope clear—listing object names and labels, with optional filtering—and notes the default exclusion of system noise. However, it does not explicitly state when to choose this over describe_object for metadata or run_soql_query for records, so usage guidance is implied rather than explicit.

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 read-only nature is stated and aligns with the readOnlyHint and idempotentHint annotations. The description adds useful behavioral context by explaining that SOQL cannot modify data, advising LIMIT to avoid runaway exploratory queries, and signaling that invalid field/object names produce errors. It doesn't discuss pagination or result shape, but annotations already cover the safety profile.

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?

Five short, purposeful sentences with the main purpose and read-only caveat front-loaded. Every sentence earns its place: purpose, safety, use cases, LIMIT guidance, and error recovery. 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?

For a general-purpose SOQL tool with two parameters and no output schema, the description covers the essential context: scope, capabilities, safety, usage guardrails, and error handling. Pagination is documented in the schema's next_url description, so the absence of that detail in the tool description is acceptable.

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 schema already provides 100% parameter coverage for query and next_url, so the baseline is 3. The description adds practical value by reinforcing the need for LIMIT in queries and pointing to describe_object for resolving invalid API names, which goes slightly 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?

Description opens with a specific verb and resource: 'Run a raw SOQL query against the Salesforce org.' It also names the tool's role as the escape hatch for filtering, joins, aggregates, and ORDER BY, which clearly distinguishes it from sibling tools like search_records, get_record, and describe_object.

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

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

The description explicitly states when to use this tool: 'anything the other tools don't cover,' and gives concrete use cases. It also gives a guardrail ('Always include a LIMIT for exploratory queries') and tells the agent what to do on errors ('check the exact API names with describe_object').

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 and idempotentHint=true, so safety is covered. The description adds that this is full-text search and lists common searchable fields, but it does not disclose result shape, default fields, or pagination behavior, which are relevant but not severe gaps given the read-only annotation coverage.

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 with no wasted words. The core function is front-loaded, and the alternative routing is given concisely in the second sentence. Every phrase 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?

The tool is moderate complexity with four documented parameters and helpful annotations. The description adequately covers purpose and usage context. A return-value or result-format note might help since there is no output schema, but the tool's search behavior is already clear enough for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all four parameters clearly. The description adds no parameter-level detail beyond mentioning searchable fields, which is not necessary because the schema handles parameter semantics effectively.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Full-text search across Salesforce records'), specifies the resource, and gives concrete examples of searchable fields. It also distinguishes itself from run_soql_query by noting this is for when the object or Id is unknown.

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

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

The description explicitly identifies when to use this tool: 'Good for find the record for X when you don't know the object or Id.' It also names the alternative for precise filtering: 'use run_soql_query instead.' This gives an agent clear routing guidance.

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 indicate this is not read-only, is destructive, and is idempotent. The description adds the important behavioral requirement that the agent must first present the exact change to the user and obtain approval before setting confirm=true. This goes beyond the annotations and covers the main side-effect risk of updating a record.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words, and the core operation is stated first. The confirmation requirement is front-loaded right after the purpose, making the most important behavioral constraint immediately visible.

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 four-parameter update tool, the description covers the purpose, the confirmation requirement, and the target resource. There is no output schema, so a note about the return value would add completeness, but all invocation-critical information is present and the annotations cover safety traits like destructiveness and idempotency.

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 input schema has 100% parameter description coverage, so the schema already explains object_type, record_id, data, and confirm. The description reinforces the confirm requirement but does not add substantial meaning beyond the schema. Baseline 3 applies because the schema carries the semantic 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?

The description uses a specific verb and resource: 'Update fields on an existing Salesforce record.' This clearly differentiates it from siblings like create_record, delete_record, and get_record, and immediately identifies the operation as an update rather than a read or creation.

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

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

The description provides clear context: it updates an existing Salesforce record. It also communicates the key prerequisite that confirm=true must be set only after user approval. It does not explicitly name alternatives like create_record or delete_record, but the update-vs-create/delete distinction is clear enough for an agent to choose correctly.

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