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

The description adds behavioral context beyond annotations: it specifies the return format (id, success), lists common required fields per object type, and provides examples. This compensates for the few annotations, though it does not mention error handling or permissions.

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 with sections for args, returns, common fields, and examples. It is concise and front-loaded with the main purpose, no unnecessary words.

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

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

Given the tool complexity (create with object_type and fields), the description covers return value, examples, and field requirements. It is mostly complete but lacks mention of potential errors, rate limits, or authentication, which would be helpful.

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

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

The description adds significant value beyond the schema: it documents common required fields for multiple object types and provides concrete examples. The schema has 100% coverage, but the description deepens understanding.

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 purpose: 'Create a new record in Salesforce.' It uses a specific verb and resource, and distinguishes from sibling tools like salesforce_get_record, salesforce_update_record, and salesforce_delete_record.

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 does not provide explicit guidance on when to use this tool versus alternatives such as salesforce_update_record or salesforce_query. It lacks context for usage boundaries.

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 mark readOnlyHint=false and idempotentHint=false. Description adds crucial behavioral context: async operation, time ranges, permission requirement, production org requirement, and caller allowlist. Goes far beyond annotations.

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

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

Well-structured with sections, but slightly long. Every sentence is informative and earns its place, though could be slightly more 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?

For a tool with 3 params, async behavior, no output schema, and multiple sandbox types, the description covers all necessary information for correct use, including monitoring and post-creation connection.

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?

Input schema has 0% description coverage, but description fully compensates: explains sandbox_name constraints, license_type differences (data, time, cost), and description field.

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 ('Create') and resource ('a new sandbox via Tooling API SandboxInfo'), and distinguishes from sibling tools like salesforce_list_sandboxes which monitors progress.

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 explains asynchronous nature, how to monitor with salesforce_list_sandboxes, and provides notes on when each license type is appropriate. Lacks explicit 'when not to use' but context 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?

The description goes beyond the annotations (destructiveHint=true) by detailing that the action cannot be undone, the record goes to the Recycle Bin, and has a 15-day restoration window. This provides critical behavioral context for an agent.

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

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

The description is concise and well-structured: front-loaded with the core action, followed by parameter details, return info, and a warning. No unnecessary words.

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

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

Given the tool's simplicity (2 required params, no output schema), the description is complete. It covers purpose, parameters, return type, and behavioral implications, requiring no additional context.

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?

Despite 100% schema coverage, the description adds value by specifying the format for record_id (15 or 18 characters) and giving examples for object_type. This helps the agent provide correct inputs without relying solely on 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's purpose: 'Permanently delete a Salesforce record.' This specific verb-resource pairing distinguishes it from sibling tools like salesforce_create_record and salesforce_update_record.

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 a clear warning about the irreversibility and Recycle Bin behavior, guiding when to use this tool (for deletion). It does not explicitly mention alternatives or when not to use, but the purpose is straightforward.

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?

Discloses that deploy is upsert-style (overwrites existing api_name), blocked when SALESFORCE_READONLY=true (including dry-runs), and requires specific permissions. Adds context beyond annotations (readOnlyHint=false, openWorldHint=true) without contradiction.

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 a clear one-sentence summary, then organized into upsert behavior, workflow, supported types, parameter details, blocking conditions, and returns. Every sentence adds value with no 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?

Covers purpose, workflow, parameters, blocking, permissions, return status. Lacks explicit details on return format or how unused parameters are handled per metadata type, but overall comprehensive given complexity.

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?

Adds significant context beyond the 100% schema coverage: e.g., 'api_name must match Salesforce naming rules'; 'body_content required for ApexClass and ApexTrigger'; workflow guidance for check_only. Schema descriptions are adequate, but the narrative enriches understanding.

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?

Clearly states the tool deploys a metadata component to Salesforce via SF CLI, specifies upsert behavior (create or update), and lists supported types. Distinguishes from sibling tools like salesforce_retrieve_metadata (retrieve) and salesforce_create_record (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?

Provides a typical workflow for creating a new Flow, including optional retrieval, authoring, dry-run, and deploy. Notes blocking when SALESFORCE_READONLY=true and required permissions. Implicitly distinguishes from similar tools by focusing on metadata deployment.

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 behavioral context beyond annotations, such as the ability to include picklist values and choose response format. It also explains the type of metadata returned. No contradictions with annotations (readOnlyHint=true, etc.).

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 with separate sections for Args and Returns, front-loading the main purpose. It is moderately sized without excessive verbosity, though some redundancy exists (e.g., repeating field details).

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

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

The description is thorough for a tool with no output schema, detailing return values (field names, types, required flags, picklist values). It fully covers all parameters and provides sufficient context for effective use.

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 describes all parameters with examples and defaults. The description's Args section repeats similar information, adding little new meaning. Thus, 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?

The description clearly states it gets metadata for a Salesforce object, listing specific details like field names and types. It distinguishes itself from siblings by explicitly indicating its use before writing SOQL queries or CRUD operations, which contrasts with querying or listing objects.

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: 'Use this to discover what fields are available before writing SOQL queries or creating/updating records.' It provides clear context for its usage, though it does not explicitly mention when not to use or alternatives like salesforce_metadata_query.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's safe. The description adds value by specifying the returned data (key limits and their structure), which goes beyond the annotation hints.

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

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

The description is concise and well-structured. It starts with a clear purpose sentence, then lists key returns, and ends with a usage note. Every sentence is necessary and provides value 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 simplicity (no parameters, no output schema), the description fully covers what an agent needs: it explains what the tool does, what it returns, and when to use it. No additional context is needed.

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 the input schema coverage is 100%. With no parameters to document, the description does not need to add parameter semantics. The baseline score of 4 is appropriate as no information is missing.

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 tool name and title directly indicate it retrieves Salesforce API limits. The description explicitly states 'Check your Salesforce org's current API usage and remaining limits,' listing specific limits like DailyApiRequests and DailyBulkApiRequests. This clearly distinguishes it from sibling tools like salesforce_query or salesforce_get_record, which operate on 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 provides a clear use case: 'Use this to monitor API consumption before running large batch operations.' While it does not explicitly state when not to use it or list alternatives, the context is sufficient for an agent to decide when to invoke this tool.

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 provide readOnlyHint, idempotentHint, etc. Description adds behavioral details: returns all fields if fields array empty, supports response_format options, and specifies return of the full record. No contradictions.

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?

Description is well-structured with a summary, bulleted args, returns, and examples. Every sentence is informative and there is no unnecessary text.

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

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

Given the tool's simplicity and good annotations, the description covers all necessary aspects: parameters, return values, examples. No output schema, but return format is explained. Complete for a get-record operation.

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% with descriptions. Description adds examples and clarifies behavior like 'If empty, returns all fields' and default response_format, adding 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?

Description clearly states 'Retrieve a single Salesforce record by its ID', providing a specific verb and resource. It distinguishes from sibling tools like salesforce_query (multiple records) and salesforce_describe_object (metadata) without needing explicit 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 implies usage: when you have a record ID and need a single record. It provides clear context but does not explicitly mention when not to use (e.g., for bulk queries or metadata).

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, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context by describing the return value ('List of objects with their names, labels, and CRUD capabilities'), which is 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 concise with clear sections (purpose, usage, args, returns). Every sentence adds value, and the structure is well-organized for quick scanning.

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 annotations, full schema coverage, and no output schema, the description adequately explains the tool's behavior and return value. It is complete for an agent to understand how to use it.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description in the Args section largely mirrors the schema (e.g., 'filter (string): Optional text to filter object names/labels (case-insensitive)'), adding minimal new meaning beyond what the schema already 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?

The description explicitly states 'List all available Salesforce objects (standard and custom) in the org,' using a specific verb and resource. It distinguishes this tool from siblings like salesforce_query (querying data) and salesforce_describe_object (describing a specific object), making its purpose clear.

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 says 'Use this to discover what objects exist before querying or manipulating data,' providing clear guidance on when to use it. It does not explicitly exclude scenarios, but the context of sibling tools implies alternatives for 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 indicate readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds behavioral context beyond these: it explains the output includes both SandboxInfo and optionally SandboxProcess lists, and emphasizes the production org requirement. No contradictions 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 well-structured with clear sections (Description, Args, Returns, Note). It is concise, no filler sentences, and all information is front-loaded. Every sentence adds value to the agent's 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?

Given the tool's complexity (list with optional progress tracking) and lack of output schema, the description completely covers input parameters, return types, and an important usage constraint (production org). No gaps for an AI agent to select and invoke 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 0%, but the description explains both parameters in the Args section: include_in_progress controls the inclusion of SandboxProcess records (default true), and response_format defaults to markdown. This adds necessary meaning that the schema lacks. The return structure is also described.

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

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

The description clearly states the tool lists all sandboxes via Tooling API SandboxInfo, distinguishing it from sibling tools like salesforce_metadata_query (for SandboxProcess) and salesforce_create_sandbox (for creation). It specifies the verb 'list', the resource 'sandboxes', and the scope 'under the production org'.

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

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

The description provides explicit guidance: it lists sandboxes and includes in-progress creations, and suggests using salesforce_metadata_query for SandboxProcess status. The note 'must be run against the PRODUCTION org' is a crucial usage constraint. However, it does not explicitly state when not to use this tool versus alternatives like salesforce_query.

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 critical behavioral context beyond annotations: it specifies use of the Tooling API, the restriction on Metadata/FullName fields requiring exactly one row, and implies it complements standard SOQL. No contradiction with annotations (readOnlyHint, etc.).

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

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

The description is concise: a clear opening statement, targeted use cases, representative examples, and a critical constraint note. Every sentence serves a purpose with no 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 and lack of output schema, the description is comprehensive. It covers purpose, applicable objects, examples, and the key single-row constraint, enabling correct agent 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 baseline is 3. The description adds usage examples for the soql parameter but does not significantly enhance meaning beyond the schema for limit and response_format.

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 executes SOQL queries using the Salesforce Tooling API for metadata objects, with specific objects listed and examples. It distinguishes from siblings like salesforce_query by explicitly noting it accesses metadata not available via standard SOQL.

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 use cases (e.g., ValidationRule, Flow) and examples, and notes the single-row constraint for Metadata/FullName fields. However, it lacks explicit 'when not to use' or comparison to alternative tools like salesforce_describe_object or salesforce_retrieve_metadata.

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, so safety is handled. The description adds value by detailing return formats (JSON/Markdown), error messaging, and the default/max limit for results. This provides behavioral context 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 well-organized: first sentence states purpose, then examples, then parameter list, then return info, then error info. Every sentence adds value, and the structure is easy to parse. No fluff.

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 a SOQL query tool, the description covers all essential aspects: query language, parameters, return format, and error handling. No output schema is provided, but the text describes the return value sufficiently. It is complete for an AI agent to invoke 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 coverage is 100%, but the description adds examples and explains the soql parameter with syntax hints, the limit parameter with defaults, and the response_format parameter with format descriptions. This goes beyond the schema's basic descriptions.

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

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

The description clearly states it executes a SOQL query to retrieve records, using a specific verb ('Execute') and resource ('Salesforce records'). It provides examples of typical queries, distinguishing it from sibling tools like salesforce_get_record (single record by ID) or salesforce_search (full-text search). No ambiguity.

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 explains when to use this tool (for SOQL queries) and gives examples of valid use cases. It doesn't explicitly list when not to use it, but the sibling tools implicitly cover alternatives. The context is clear enough for an AI agent to decide.

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 that the tool is safe for read-only mode and specifies the return format (raw XML, .cls/.trigger body) and prerequisites (SALESFORCE_SF_CLI_USERNAME). No contradictions 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 well-structured with a clear first line, bullet points for usage, a list of supported types, and separate sections for args, requirements, and return value. Every sentence serves a purpose, and there is no 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 no output schema, the description compensates by stating the return format. It covers all parameters, prerequisites, and usage patterns. The tool has moderate complexity, and the description provides sufficient context for an agent to select and 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 coverage is 100%, so the schema already documents each parameter. The description restates the object_name requirement but does not add new semantic information 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?

The description clearly states the tool retrieves a metadata component as XML via SF CLI, lists specific use cases (inspect existing Flow, fetch, modify, redeploy), and enumerates supported metadata types. This provides a specific verb+resource and distinguishes it from sibling tools like salesforce_query or salesforce_deploy_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?

The description provides explicit use cases ('Use this to:') and notes the prerequisite environment variable. While it does not explicitly exclude other contexts, the listed use cases and the context of sibling tools make it clear when to use this tool versus alternatives.

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 declare readOnlyHint, idempotentHint true and destructiveHint false, which the description does not contradict. The description adds behavioral context by explaining the SOSL search mechanism, return format (searchRecords), and that results are grouped by object type. It could mention any limitations like pagination or SOQL differences, but the additional context is valuable.

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?

Description is well-structured: starts with purpose, then usage guidance, followed by example queries, and finally parameter descriptions. Every sentence adds value; no redundancy or filler. 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 no output schema, the description adequately covers return values (JSON with searchRecords or Markdown formatted by object type). Both parameters are fully explained with examples. The tool's complexity (SOSL search) is well-addressed for an AI agent to use 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 coverage is 100%, so baseline is 3. The description adds significant meaning beyond the schema: it explains the SOSL parameter with multiple examples, clarifies that the query must be valid SOSL, and details the response_format parameter including default value and output behavior. This greatly aids correct invocation.

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 specifies 'Search across multiple Salesforce objects using SOSL', providing a specific verb and resource. It distinguishes from sibling tools like salesforce_query (likely for single object SOQL queries) by emphasizing multi-object and full-text search capability.

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 'Use SOSL when you want to search across multiple object types at once or do full-text search', providing clear when-to-use guidance. It implicitly contrasts with salesforce_query for single object queries, and the example queries further clarify usage scenarios.

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?

Beyond annotations (readOnlyHint=false, idempotentHint=true, etc.), the description adds important behavioral details: 'Only the provided fields are updated; other fields remain unchanged' and 'To clear a field, set its value to null.' This provides valuable context for the agent.

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 with a clear summary, Args, Returns, Notes, and Examples sections. It is concise, front-loaded, and every sentence serves a purpose. No unnecessary 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 modest complexity (3 required parameters, no output schema), the description is complete. It explains all parameters, notes on field update behavior, and provides examples. It does not cover error cases or permissions, but these are often outside the scope of a tool description.

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 adds value by providing examples, clarifying record ID length (15 or 18 characters), and explaining how to clear fields with null. These details enhance understanding 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's purpose: 'Update fields on an existing Salesforce record.' It uses a specific verb ('update') and resource ('existing Salesforce record'), and it distinguishes itself from sibling tools like create, get, delete, query, and search.

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 does not explicitly state when to use this tool versus alternatives. While the name and sibling list imply its use case (modifying an existing record), there is no guidance on when not to use it or how to choose among related tools.

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