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

With no annotations provided, the description carries the full burden of disclosure. It clearly states this is a fetch operation (safe, read-only) and explicitly lists the returned data fields, including 'all custom fields'. It does not mention error handling or response structure, but for a simple, non-destructive retrieval, the description provides adequate 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 a single sentence, front-loaded with the verb and resource, and then lists return fields. Every word adds value, with no fluff or redundancy. It is appropriately sized for a simple single-parameter tool.

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

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

The tool is simple (one param, no output schema) and the description adequately covers what the tool does and what it returns. The list of return fields provides some expectations, though it does not describe the response shape or potential errors. Given the low complexity, this is fairly 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?

The single parameter issueKey is fully described in the schema with format and example (PROJECT-NNN). The description references 'by issue key' but adds no additional meaning beyond the schema. Since schema coverage is 100%, a baseline 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 resource 'Jira story by issue key', making the tool's primary purpose unmistakable. It also enumerates the return fields, further clarifying scope. This clearly distinguishes it from sibling tools like jira_search_stories (search) and jira_update_story_status (update).

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

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

The description clearly implies usage: use when you need a single Jira story by key. It does not explicitly state when not to use it or alternatives (e.g., use search when you don't have a key), but the context is clear enough for an agent to infer the appropriate scenario. The lack of explicit exclusions keeps it at 4 rather than 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that the tool supports plain text with paragraphs separated by blank lines, which is a useful format constraint. However, it does not disclose potential side effects, authentication requirements, error behavior, or whether the comment is immediately visible, leaving some behavioral aspects implicit.

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

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

The description is three concise sentences that front-load the primary action and then provide context. Every sentence contributes value without repetition or fluff. It is appropriately sized for a simple two-parameter tool.

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

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

For a simple tool with two parameters, no output schema, and no annotations, the description covers the essential context: what it does, when to use it, and the input format. It does not explain return values, but none are expected here. It could mention whether the comment is appended to an existing thread, but the lack of output schema makes this less critical.

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% coverage with descriptions for both parameters (body and issueKey). The description adds usage context but does not add new meaning about the parameters themselves. The text about plain text and paragraphs aligns with the body schema description, but does not go beyond it.

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 posts a comment to a Jira story, using a specific verb and resource. It is distinct from sibling tools like jira_update_story_status and jira_search_stories, as no other sibling handles comments. The provided use cases reinforce the purpose without 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 explicitly lists when to use the tool: 'to document deployment results, ask for clarification, or provide status updates.' This provides clear context and avoids confusion with sibling tools, though it does not explicitly state when not to use it or name alternatives. The guidance is sufficient for an agent to select this tool for comment-related actions.

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?

No annotations are provided, so the description bears the full burden of disclosing behavior. It does state that the tool 'Returns matching issues with full details', which is useful, but it doesn't mention whether the operation is read-only, whether it enforces issue type 'Story', how pagination works (beyond schema defaults), or what 'full details' includes. This leaves some ambiguity for an agent, so a mid-range score is appropriate.

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: a clear statement of purpose and an example JQL. It is concise, front-loaded with the core verb and resource, and contains no filler. Every sentence earns its place; the example is directly actionable.

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

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

The tool has a moderate complexity (pagination, required jql) and no output schema, so the description should clarify return values. It states 'Returns matching issues with full details', which gives a general idea but not the structure. Combined with the rich schema descriptions and the example, an agent has sufficient context to invoke the tool correctly, though a clearer definition of 'full details' would improve completeness.

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%: all three parameters (jql, startAt, maxResults) have detailed descriptions with examples, defaults, and constraints. The tool description adds an example JQL, but it largely duplicates examples already in the schema. Since the schema already provides complete parameter semantics, the description's added value is marginal, warranting the baseline score of 3.

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 function: 'Search Jira stories using JQL (Jira Query Language)'. It specifies the verb (search), resource (Jira stories), and method (JQL), which distinguishes it from sibling tools like jira_get_story (which fetches a single story) and jira_update_story_status. The example JQL further reinforces the intended use.

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

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

The description provides clear context on how to use the tool (by constructing a JQL query) and gives a concrete example. However, it does not explicitly state when to use it over alternatives (e.g., 'use this when you need to search by criteria rather than fetching a specific story'). This is a minor gap, but the usage context is clear enough for an agent to choose it appropriately.

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?

No annotations are provided, so the description carries full responsibility for disclosing side effects. It only states that transitions are workflow-dependent, which is a useful constraint, but it omits any information about permissions, reversibility, or what the operation returns. This is minimal behavioral disclosure for a mutation tool.

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

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

The description is two sentences long, front-loaded with the primary action, and includes a useful note about workflow dependency. Every sentence contributes meaning without unnecessary padding.

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 covers the core purpose and acknowledges workflow variability, but it does not explain how to discover available transitions or what the tool returns. Given the lack of an output schema and the absence of guidance on preconditions, the description is adequate but not fully self-sufficient.

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

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

The input schema already provides detailed descriptions for both parameters, including format examples and exact-match requirements. The tool description adds no additional parameter information beyond restating common statuses already listed in the schema. With 100% schema coverage, the baseline 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 clearly states the tool's function with a specific verb ('Transition') and resource ('a Jira story'). It distinguishes from sibling tools like jira_get_story and jira_post_comment by focusing on status changes.

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 context that transitions depend on workflow configuration, implying the agent may need to check the current status first. However, it does not explicitly mention when to use this tool versus alternatives or give exclusions. No alternatives are named, so it earns a mid-level score.

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

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

With no annotations, the description carries the burden. It correctly indicates a read operation ('retrieve') and mentions output data, but doesn't disclose error behavior (e.g., invalid execution ID), rate limits, or whether partial data is returned before completion. This is adequate but not rich.

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 succinct sentences: the first states the operation and the second states the use case. No redundant words, and the structure front-loads the core purpose.

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

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

For a simple one-parameter read tool with no output schema, the description covers the essential semantics and use case. It omits potential error handling, but given the simplicity, this is not a significant gap.

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

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

Schema coverage is 100%, so the schema already documents the executionId parameter with its source and purpose. The description adds no further parameter detail, so baseline 3 applies.

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

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

The description clearly states the tool retrieves the status and output data of an n8n workflow execution by ID. This specific verb-resource pairing distinguishes it from sibling n8n_trigger_workflow, which creates executions.

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 says to use this for polling whether a triggered workflow completed successfully, giving clear context. It doesn't list exclusions or explicitly name alternatives, but the sibling relationship is implied.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It indicates a side-effectful action ('kick off' a pipeline) but does not disclose potential consequences, authentication requirements, or response behavior. The schema mentions waitForResponse semantics, but that is schema text, not the description. This lack of transparency for a triggering action is a significant gap.

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, front-loaded with the primary action. Every sentence earns its place: the first states the core functionality, the second illustrates applicability. No filler or 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?

The tool is moderately complex with a webhook trigger and optional waitForResponse, but the schema covers parameters well. The description lacks guidance on follow-up actions, such as using n8n_get_execution_status to monitor the triggered workflow, and does not mention error handling or authentication context. It is adequate but leaves gaps that could affect an agent's end-to-end usage.

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 each parameter is already documented in the schema. The description adds a brief example use case (Jira issue key) but does not expand meaningfully on parameter semantics beyond what the schema provides. Baseline of 3 is appropriate as the schema does the heavy lifting.

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 identifies the action ('Trigger a specific n8n workflow by its webhook URL') and the resource (n8n workflow). It also distinguishes from sibling tools by focusing on triggering rather than status retrieval, and provides a concrete use case involving the Salesforce pipeline.

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

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

The description implies when to use the tool ('to kick off the full Salesforce automation pipeline') and gives a concrete example (sending a Jira issue key). It does not explicitly state exclusions or alternatives, but the context with n8n_get_execution_status suggests it is the entry point followed by status checks. A clear 'when not to use' is absent, leaving it slightly below explicit 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?

With no annotations, the description carries the full burden. It mentions 'using the Tooling API' but fails to disclose whether creation is immediate or staged, what permissions are needed, or what side effects might occur (e.g., field being unavailable until deployment). It also does not describe error behavior or impact on existing data.

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 long and front-loaded with the core purpose. The second sentence, however, ends with 'and more' which is redundant given the enum is exhaustive, making it slightly less crisp but still efficient.

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

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

This is a complex creation tool with 17 parameters, 4 required, and no output schema. The description offers only a basic statement of intent and fails to explain what happens on success, how errors are reported, or how this fits into a broader Salesforce metadata lifecycle. Minimal for the tool's 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?

Schema coverage is 100% — all 17 parameters have descriptions in the input schema. The description's phrase 'Supports all standard field types including...' adds little beyond the schema's exhaustive enum. No additional parameter relationships or usage detail are provided in the description.

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 'Create a custom field on a Salesforce object using the Tooling API', using a specific verb + resource. This distinguishes it from sibling tools like salesforce_create_validation_rule (validation rule creation) and salesforce_get_object_fields (reading 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?

The description gives no explicit guidance on when to use this tool vs alternatives. It does not mention that this is for individual field creation rather than bulk deployment (salesforce_deploy_metadata), nor does it list any prerequisites or context for choosing 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the Tooling API and the rule's logic, but it does not disclose important traits such as whether the rule requires deployment, if it is reversible, permission requirements, or what happens on errors. This is a significant gap for a mutation tool.

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

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

The description consists of two concise sentences that front-load the primary verb and resource. It provides useful context about the rule's behavior without any waste. 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?

Despite the tool having 7 parameters and no output schema, the description fails to provide necessary context. It does not mention deployment requirements, permissions, the creation process via Tooling API, or validations on the formula. The schema covers parameters, but the behavioral and operational context is incomplete for a create 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 description coverage is 100%, so the baseline is 3. The description includes terms like 'error condition formula' and 'error message' that map to parameters, but adds no new meaning beyond the schema. The schema already provides detailed descriptions and examples, so the description does not compensate for any gaps.

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 function: 'Create a validation rule on a Salesforce object using the Tooling API.' It also explains the rule's behavior (evaluates an error condition formula and displays an error message when the formula returns true), which distinguishes it from sibling tools like salesforce_create_custom_field and salesforce_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 description gives no explicit guidance on when to use this tool versus alternatives. It does not mention any 'when' or 'when not' conditions, prerequisites, or reference to sibling tools. The only implied context is that it creates validation rules, but there is no stated use case or 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?

With no annotations, the description carries full responsibility for behavioral disclosure. It fails to mention that deployments are typically asynchronous, that a deployment ID is returned, or that changes may be rolled back if errors occur. It also doesn't state potential side effects beyond the obvious deployment action, which is a significant gap for a mutating operation.

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 concise sentence, front-loaded with the core action and requirement. No filler or redundant information, earning a high score for efficiency.

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

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

Despite having 6 parameters, no annotations, no output schema, and a sibling for status checking, the description is minimal. It doesn't explain the deployment workflow, what the tool returns, or how to leverage the result. This is insufficient for the complexity and mutating nature of the 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 description coverage is 100%, so parameters are already well-documented. The description adds no additional meaning beyond restating the ZIP requirement, which is already present in the schema. 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 the tool triggers a Salesforce metadata deployment via the Metadata API, with a specific requirement for a base64-encoded ZIP. This distinguishes it from sibling tools like salesforce_get_deployment_status and jira_get_story.

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

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

No guidance is provided on when to use this tool versus alternatives such as salesforce_get_deployment_status. The description doesn't mention the deployment lifecycle or that users may need to check status separately, leaving the agent to infer usage context.

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

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

With no annotations, the description carries the full burden. 'Poll' implies a read-only, potentially repeated operation, and it discloses what is returned (component counts, errors, test results). However, it does not mention error behavior (e.g., invalid ID), what happens if deployment is still in progress, or any rate limits.

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

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

Two short sentences convey the essential information. The first sentence front-loads the action and resource, and the second lists return values. No wasted words.

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

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

This is a simple single-parameter tool with no output schema and no annotations. The description adequately explains the purpose and return values, covering component counts, errors, and test results. It could improve by clarifying the 'status' aspect (e.g., states like InProgress, Succeeded) and error conditions, but it is sufficient for basic 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 parameter is already well-documented in the schema. The tool description adds little beyond restating 'deployment ID' from the schema, though the schema's reference to salesforce_deploy_metadata is helpful.

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 ('Poll the status'), the specific resource ('Salesforce metadata deployment'), and the identifier ('deployment ID'). It also lists key return elements, distinguishing it from other tools like salesforce_deploy_metadata and n8n_get_execution_status.

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 after a deployment is initiated, and the parameter description explicitly references salesforce_deploy_metadata as the source of the ID. However, it does not provide explicit 'when not to use' or name alternative tools for situations where polling is not appropriate.

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?

No annotations are provided, so the description should carry the burden of behavioral disclosure. It mentions using the REST API describe endpoint and lists the returned attributes, which is helpful, but it does not explicitly state that this is a read-only operation, whether authentication is required, or any limiting constraints. The description is acceptable but not richly transparent.

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, well-structured sentence that front-loads the main purpose and immediately states the return content. Every word adds value, with no redundancy or unnecessary detail.

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 one-parameter tool with no output schema, the description is complete: it explains what the tool does, how it works (via describe endpoint), and what it returns. There are no hidden complexities or missing prerequisites that would affect an agent's ability 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?

The schema already fully describes the only parameter (objectName) with an example and explanation, so schema coverage is 100%. The description does not add additional parameter semantics beyond confirming that it operates on a Salesforce object, which aligns with the baseline of 3 for high schema coverage.

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

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

The description states a specific verb ('Query'), a precise resource ('all existing fields on a Salesforce object'), and the method ('using the REST API describe endpoint'). It clearly differentiates from siblings like salesforce_query (which queries records) and salesforce_create_custom_field (which creates 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?

The description clearly implies when to use this tool: when field metadata is needed (names, labels, types, etc.), not when querying records. It does not explicitly name alternative tools or state exclusions, but the context is sufficiently clear for an agent to select it appropriately among the listed 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?

No annotations are provided, so the description carries full burden. It implies a read-only operation through 'query' but does not explicitly state it is safe, nor does it mention rate limits, error handling, or result pagination. Some important behavioral details are missing.

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

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

Two sentences, front-loaded with the action, and the second sentence adds useful context without redundancy. No fluff or unnecessary detail.

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

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

The tool has only two simple parameters and no output schema, but the description does not mention return value format, potential errors, or read-only guarantees. It covers the basic purpose and use cases but leaves some gaps for a complete picture.

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 parameters are well-documented in the schema. The description adds little beyond general purpose, not enhancing the parameter meaning beyond what the schema already provides. 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 clearly states the tool 'Execute a SOQL query against Salesforce' and explicitly mentions it returns results. It distinguishes from siblings like salesforce_get_object_fields (metadata retrieval) and deployment tools by focusing on data querying.

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 concrete use cases: 'verify field values after deployment, check existing records, or validate configuration.' This gives clear context for when to use the tool, though it does not explicitly mention when not to use it or alternatives.

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