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

Annotations indicate readOnlyHint=false and openWorldHint=true, suggesting mutable and unpredictable behavior. The description adds context about error conditions and the custom nature of endpoints, but doesn't disclose critical behavioral traits like authentication needs, rate limits, or potential side effects beyond what annotations imply. No contradiction with annotations exists.

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 appropriately sized with two sentences that are front-loaded with the main purpose. It avoids unnecessary details, though it could be slightly more structured to separate usage notes from parameter explanations.

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

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

Given the complexity of executing custom Apex endpoints, no output schema, and annotations covering only basic hints, the description is moderately complete. It explains the purpose and error case but lacks details on return values, authentication, or how to handle the open-world nature implied by annotations.

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

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

Schema description coverage is 0%, so the description must compensate. It partially explains 'action' as 'the URL path after /services/apexrest/', but doesn't clarify 'method' (defaults to GET) or 'data' (payload for requests). With 3 parameters and low coverage, the description adds minimal semantic value beyond the schema.

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

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

The description clearly states the tool 'Call a custom Apex REST endpoint' with specific details about the URL structure ('path after /services/apexrest/') and that these are 'org-specific REST services written in Apex by developers.' It distinguishes from generic REST tools by specifying Apex endpoints, though it doesn't explicitly differentiate from sibling 'restful' or 'tooling_execute' tools.

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

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

The description implies usage for custom Apex REST endpoints and mentions an error condition if none exist, providing some context. However, it doesn't explicitly state when to use this tool versus alternatives like 'restful' or 'tooling_execute', nor does it provide clear exclusions or prerequisites beyond the error case.

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 adds valuable behavioral context beyond the annotations: it specifies that the tool returns the new record's ID on success, mentions the need for required fields (implied from describe_object), and notes that data dict keys must be field API names. The annotations only indicate it's not read-only (readOnlyHint: false), so the description compensates well but doesn't cover aspects like error handling or rate limits.

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

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

The description is appropriately sized and front-loaded: it starts with the core purpose, followed by usage guidelines, parameter details, and an example. Every sentence adds value without redundancy, making it efficient and well-structured.

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

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

Given the tool's complexity (mutation with 2 parameters, no output schema, and annotations only covering read-only status), the description is mostly complete: it covers purpose, usage, parameters, and return value. However, it lacks details on error cases or authentication needs, leaving minor gaps for a mutation tool.

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

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

With 0% schema description coverage, the description fully compensates by explaining both parameters: 'object_name' is clarified as the object name (e.g., 'Contact'), and 'data' is described as a dict of field values with keys as field API names. It adds meaning beyond the bare schema, though it doesn't detail data types or constraints beyond the example.

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

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

The description clearly states the tool's purpose with a specific verb ('Create') and resource ('Salesforce record'), distinguishing it from siblings like update_record or delete_record. It specifies what it does: creates a new record given an object name and field 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 provides explicit guidance on when to use this tool versus alternatives: it instructs to 'Call describe_object first to see required fields and valid picklist values,' indicating a prerequisite and distinguishing it from describe_object. It also implies usage for creating new records, not updating or deleting.

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 destructiveHint=true and readOnlyHint=false, but the description adds valuable context: it clarifies that deletion is permanent via the API (cannot be undone) and specifies that records go to the Recycle Bin with a 15-day admin recovery window. This enhances understanding beyond the basic 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 front-loaded with the core action ('Permanently delete a Salesforce record') and efficiently adds critical behavioral details in two concise sentences. Every sentence earns its place by providing essential information 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?

Given the tool's complexity (destructive operation) and lack of output schema, the description is reasonably complete: it covers the action, permanence, and recovery details. However, it could mention potential side effects (e.g., related records) or error conditions to be fully comprehensive.

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

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

With 0% schema description coverage, the description doesn't explain the parameters (object_name and record_id). However, the schema itself provides titles ('Object Name', 'Record Id'), so the baseline is 3 as the schema carries the burden. The description adds no parameter-specific information.

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 specific action ('permanently delete') and resource ('a Salesforce record'), distinguishing it from sibling tools like update_record or get_record. It precisely communicates the irreversible nature of the operation.

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 about when to use this tool (for permanent deletion) and implies when not to use it (if recovery might be needed, since it mentions admin recovery within 15 days). However, it doesn't explicitly name alternatives like update_record for modifications or list_objects for browsing.

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=true, indicating a safe read operation. The description adds valuable context beyond this by specifying the scope of metadata returned (fields, relationships, picklist values, record types) and listing common field types and standard/custom object naming conventions, which helps the agent understand what to expect without contradicting 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 efficiently structured: the first sentence states the purpose and usage guideline, followed by specifics on metadata content and examples. Every sentence adds value without redundancy, making it easy to parse and front-loaded with key information.

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

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

Given the tool's complexity (metadata retrieval with rich output), the description is complete enough: it details what metadata is returned, provides usage context, and lists examples, compensating for the lack of output schema. With annotations covering safety, no critical gaps remain for agent decision-making.

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

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

With 0% schema description coverage and only one parameter, the description compensates by providing semantic context: it implies the parameter is a Salesforce object name (e.g., 'Account' or custom object ending in '__c'), though it doesn't explicitly name the parameter or detail syntax. This adds meaningful guidance beyond the bare schema.

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

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

The description clearly states the specific action ('Get complete metadata') and resource ('for a Salesforce object'), distinguishing it from siblings like list_objects (which lists objects) or get_record (which retrieves data records). It explicitly mentions what metadata is included: fields, relationships, picklist values, and record types.

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 explicit guidance on when to use this tool ('Call this before querying or writing to an unfamiliar object'), distinguishing it from query/write tools like run_soql_query or create_record. It also implies when not to use it (for familiar objects or direct data operations).

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 provide readOnlyHint=true, indicating a safe read operation. The description adds valuable behavioral context beyond annotations: it specifies what data is returned ('all readable fields'), explains ID format constraints (15 or 18 characters with type prefixes), and references object type codes. It doesn't mention rate limits or authentication needs, but adds useful operational details.

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?

Perfectly structured and concise: first sentence states core purpose, second explains ID format, third provides usage alternatives. Every sentence adds essential information with zero waste, and key details are 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 read-only tool with annotations covering safety, the description provides excellent context: purpose, usage guidelines, ID format details, and return scope. Without an output schema, it clarifies what's returned ('all readable fields'). Minor gap: doesn't specify error behavior or pagination (though likely not needed for single-record retrieval).

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

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

Schema description coverage is 0%, so the schema provides no parameter documentation. The description adds some semantic context: it explains record_id format (15/18 character strings with type prefixes) and implies object_name relates to Salesforce objects, but doesn't explicitly define object_name or provide examples. It partially compensates for the schema gap but leaves object_name ambiguous.

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 specific action ('Get a single Salesforce record by its ID') and resource ('Salesforce record'), distinguishing it from siblings like run_soql_query (for finding IDs) or create_record/update_record (for write operations). It provides precise scope ('Returns all readable fields').

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 when to use this tool ('Get a single Salesforce record by its ID') and when to use alternatives ('Use run_soql_query or run_sosl_search to find record IDs if you only have a name or email'), providing clear guidance on tool selection among siblings.

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 declare readOnlyHint=true, which the description aligns with by describing a listing operation. The description adds valuable behavioral context beyond annotations: it explains the return format (name, label, queryable, createable, custom), mentions standard vs. custom object patterns, and clarifies the search parameter's substring filtering 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 efficiently structured: first sentence states purpose, second explains returns, third covers the parameter, fourth gives examples, fifth distinguishes object types, and sixth guides next steps. Every sentence adds value with zero redundancy, and key information is front-loaded.

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

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

Given the tool's moderate complexity (read-only listing with one optional filter), rich annotations (readOnlyHint), and the presence of an output schema (which handles return values), the description is complete. It covers purpose, usage context, parameter semantics, output explanation, and integration with sibling tools, leaving no gaps for the 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?

With 0% schema description coverage for the single 'search' parameter, the description fully compensates by explaining its purpose ('filter by name/label substring') and providing examples of object names. This adds essential meaning beyond the bare schema, though it doesn't detail exact matching rules or case sensitivity.

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 specific action ('List all Salesforce objects') and resource ('in this org'), distinguishing it from siblings like describe_object (for fields) and SOQL/SOSL tools (for data queries). It explicitly mentions both standard and custom objects, providing concrete examples.

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 explicit guidance on when to use this tool ('first step when exploring an unfamiliar org' and 'when you need to find a custom object') and when to follow up with alternatives ('Follow up with describe_object to see fields'). It distinguishes this from query tools by positioning it as a discovery step.

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 indicate readOnlyHint=false and openWorldHint=true, meaning the tool can perform write operations and has broad capabilities. The description adds valuable context beyond this: it specifies that the path is 'relative to /services/data/vXX.0/' and 'Method defaults to GET,' which are critical behavioral details not covered by annotations. However, it doesn't mention potential risks like data destruction or authentication requirements, leaving some gaps in transparency.

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 well-structured and front-loaded: the first sentence states the core purpose, followed by usage guidelines and common examples. Every sentence earns its place by providing essential information—no fluff or redundancy. The bulleted list of common paths is efficient and enhances clarity without verbosity.

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

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

Given the tool's complexity (open-world, multiple parameters) and lack of output schema, the description is largely complete. It covers purpose, usage, key parameters, and behavioral context. However, it doesn't explain return values or error handling, which could be important for an agent invoking raw API calls. With annotations providing some safety context, this is a minor gap rather than a critical omission.

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

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

Schema description coverage is 0%, so the description must compensate. It provides meaningful semantics for parameters: it explains that 'path' is relative to a base URL and lists common examples, clarifies that 'method' defaults to GET, and implies 'params' and 'data' are for query parameters and request bodies respectively through context. This adds substantial value beyond the bare schema, though it doesn't detail all parameter nuances like data formats.

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

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

The description clearly states the tool's purpose: 'Execute a raw Salesforce REST API call.' It specifies this is an 'escape hatch for API endpoints not covered by other tools,' which explicitly distinguishes it from sibling tools that handle specific operations like create_record, delete_record, run_soql_query, etc. The verb 'execute' and resource 'Salesforce REST API call' are specific and unambiguous.

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 explicit guidance on when to use this tool: as an 'escape hatch for API endpoints not covered by other tools.' This directly contrasts it with all sibling tools listed, which cover specific operations. It also includes common use cases (e.g., listing objects, describing objects, running reports) to illustrate scenarios where this tool is appropriate, effectively guiding the agent away from using more specialized siblings.

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 adds valuable behavioral context beyond the readOnlyHint annotation. It warns 'Always include LIMIT to avoid large result sets' (performance guidance), describes the result structure ('Results include totalSize, done, and records array'), and provides syntax examples for relationship queries. No contradiction with 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 efficiently structured with zero wasted sentences. It starts with the core purpose, immediately provides usage guidelines, then offers syntax examples and best practices. Every sentence adds essential information for correct tool invocation.

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

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

Given the complexity of SOQL queries and the absence of output schema, the description provides complete context: purpose, usage guidelines, syntax examples, common objects, relationship query patterns, performance warnings (LIMIT), prerequisite tools (describe_object), and result structure. This fully compensates for the lack of structured output documentation.

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

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

With 0% schema description coverage for the single 'query' parameter, the description fully compensates by explaining SOQL syntax, common objects, custom object/field naming conventions, relationship query patterns, and the importance of LIMIT clauses. This provides comprehensive semantic guidance for constructing valid queries.

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 verb 'Execute' and resource 'SOQL query', with specific syntax examples. It explicitly distinguishes from sibling run_sosl_search by stating 'Use SOQL when you know which object to query', providing clear differentiation.

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 explicit guidance on when to use this tool vs. alternatives: 'Use SOQL when you know which object to query. Use run_sosl_search instead when searching by keyword across multiple objects.' It also mentions calling describe_object first if field knowledge is lacking, offering clear prerequisites.

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 provide readOnlyHint=true, but the description adds valuable behavioral context beyond this: it explains the SOSL syntax format, provides a concrete example, specifies wildcard behavior (* and ?), and mentions the minimum 2-character requirement. These are operational details not covered by annotations.

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

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

The description is efficiently structured with clear sections: purpose statement, syntax format, usage guidelines, example, and technical details. Every sentence adds value with no redundancy. The information is front-loaded with the core purpose first.

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 single-parameter tool with read-only annotation but no output schema, the description provides excellent context about what the tool does, how to use it, and what to expect. The main gap is lack of information about return format or result structure, but given the annotations cover safety and the description covers usage thoroughly, it's mostly complete.

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

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

With 0% schema description coverage for the single 'search' parameter, the description compensates well by explaining what the parameter should contain: it shows the full SOSL syntax pattern, provides an example with {Acme} placeholder, and explains wildcard usage. This gives meaningful context about parameter content beyond just being a string.

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

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

The description clearly states the tool's purpose with specific verb ('Search') and resource ('multiple Salesforce objects by keyword using full-text search'). It distinguishes itself from sibling tools by specifying it's for SOSL search across multiple objects, unlike run_soql_query which is for structured filtering.

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 explicit guidance on when to use this tool ('when you don't know which object contains the data, or need to search across Account, Contact, Lead, Opportunity simultaneously') and when to use an alternative ('Use run_soql_query instead for structured filtering'). This gives clear context for tool selection.

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 indicate readOnlyHint=false and openWorldHint=true, suggesting mutable operations and flexible endpoints. The description adds valuable context by specifying the Tooling API's focus on metadata/developer objects and providing concrete usage examples, though it doesn't detail authentication needs, rate limits, or mutation consequences beyond the annotations' scope.

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 front-loaded with the core purpose, followed by specific object examples and clear usage guidelines. Every sentence earns its place with no wasted words, efficiently conveying essential information in a well-structured format.

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

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

Given the tool's complexity (3 parameters, 0% schema coverage, no output schema), the description provides strong purpose and usage context but lacks full parameter documentation. It compensates well with examples and sibling differentiation, though more parameter details would enhance completeness for this open-world API tool.

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

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

Schema description coverage is 0%, so the description carries full burden for parameter meaning. It provides examples showing 'action' as a query string path (e.g., 'query/?q=SELECT...'), but doesn't explain 'method' or 'data' parameters. This adds some value but leaves gaps, aligning with the baseline for partial compensation.

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 specific action ('Execute a Salesforce Tooling API call') and resource ('metadata and developer objects'), listing examples like ApexClass and CustomField. It distinguishes from sibling tools by explicitly contrasting with run_soql_query for regular data queries.

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 explicit guidance on when to use this tool ('for metadata inspection') versus alternatives ('Use run_soql_query for regular data queries'), directly addressing sibling tool differentiation with clear context and exclusions.

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 indicate readOnlyHint=false (mutation), which aligns with 'Update'. The description adds context about partial updates ('Only include fields you want to change') and the return behavior ('Returns HTTP 204 on success'), but doesn't cover permissions, rate limits, or error handling.

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 and an example are front-loaded with essential information, with no wasted words; the example efficiently illustrates usage 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 mutation tool with no output schema and low schema coverage, the description covers purpose and basic behavior but lacks details on error cases, authentication, or integration with sibling tools, leaving gaps for 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?

With 0% schema description coverage, the description compensates by explaining the 'data' parameter's purpose ('fields you want to change') and providing an example with concrete values, though it doesn't detail 'object_name' or 'record_id' formats beyond the example.

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 verb ('Update'), resource ('fields on an existing Salesforce record'), and scope ('Only include fields you want to change'), distinguishing it from siblings like create_record (creates new) and delete_record (removes).

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

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

The description implies usage for modifying existing records and provides an example, but lacks explicit guidance on when to use this versus alternatives like create_record or delete_record, or prerequisites like authentication needs.

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