sf-docs-mcp

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the search scope ('class documentation, methods, and signatures') but does not disclose whether the operation is read-only, what the return format looks like, how errors are handled, or any limits (e.g., pagination). This is similar to the update_drive example where a mutation with no annotations received a 2 due to missing context.

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 concise sentences, with the first stating the primary action ('Look up an Apex class or method by name') and the second scoping the search domain. Every word is purposeful, and there is no unnecessary repetition or 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?

For a simple two-parameter lookup tool with a well-documented schema, the description adequately indicates what it does and its domain. However, there is no output schema, and the description does not explain return values or provide guidance on when to use this tool over the many siblings. Adding a note about alternatives or result format 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?

The input schema already provides complete descriptions for both parameters (className and namespace), yielding 100% schema coverage. The description does add the concept of 'look up by name', which aligns with className, but it does not provide extra semantic detail beyond the schema. Thus 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 uses a specific verb ('look up') and resource ('Apex class or method'), and explicitly scopes the search to the 'apex-reference domain' for 'class documentation, methods, and signatures'. This clearly distinguishes it from sibling tools like sf_object_reference or sf_search, which target different domains or generic searches.

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 Apex reference lookups by specifying that it searches the apex-reference domain, but it does not explicitly state when to use this tool over alternatives such as sf_search or sf_object_reference, nor does it mention any exclusions or when not to use it. Usage guidance is implicit rather than explicit.

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

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

No annotations are present, so the description takes on responsibility for behavior. It discloses that the tool returns snippets with language, source file, and surrounding context, and implies read-only search. It doesn't cover result limits, error cases, or access requirements, but for this tool type the core behavior is covered.

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 action and resource, then a brief value statement. No filler; each sentence earns its place.

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

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

Given no output schema and no annotations, the description covers purpose, main output fields, and an example use case. It is sufficient for a simple lookup tool, though it could mention how domain filters affect results or differentiate from generic search.

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 covers all four parameters with descriptions (100% coverage), so baseline is 3. The description adds little param-specific detail beyond the schema, only relating output fields to language and context.

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

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

Description opens with a clear verb ('Find') and specific resource ('working code examples from Salesforce documentation'), and further clarifies output as code snippets. It doesn't explicitly contrast with sibling search tools like sf_search or sf_semantic_search, so it falls just short of full 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?

States it is 'Great for learning patterns and copy-paste solutions,' giving clear use context. It does not mention when to prefer alternatives or exclusions, but provides enough orientation for a search 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool searches documentation and provides explanation, common causes, and resolution steps. This is meaningful behavioral context, though it omits caveats like accuracy or access requirements.

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 concise sentences that front-load the primary purpose and then quickly explain the tool's process and output. Every word earns its place.

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

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

For a simple one-parameter tool with no output schema, the description is complete enough: it states what the tool does and what it returns (explanation, causes, resolution steps). It could add more detail on output formatting or search scope, but it covers the essentials.

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 fully documents the single required parameter with examples, and schema description coverage is 100%. The description adds no additional parameter-specific detail beyond what the schema provides, so 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 uses a specific verb ('Explain') and resource ('Salesforce error message or exception'), and the focus on error diagnosis clearly distinguishes it from sibling tools like sf_search or sf_semantic_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 implies when to use the tool (when you encounter a Salesforce error to explain), but it does not explicitly state when to use it over alternatives or provide exclusions. Context is clear but guidance is implied rather than explicit.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It suggests a read-only navigation tool but never explicitly states this or covers return format, error behavior, pagination, or other side effects. It essentially describes purpose, not 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 compact, front-loaded with the key concept, and uses a clear second sentence to list capabilities. It omits the 'search' action, but the text is appropriately concise and free of filler.

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

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

This is a five-parameter tool with no output schema or annotations, and the description only highlights four capabilities, leaving the 'search' action unsupported. It gives no hints about return values or action-specific combinations, though the schema fills in parameter meaning. It is minimally viable but not fully complete for an agent navigating complex graph queries.

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 describes all five parameters with 100% coverage, including an enum for actions and specific examples for nodeId, service, and namespace. This matches the baseline of 3 for high schema coverage; the description adds no further parameter-level detail, but the schema already provides adequate semantics.

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 identifies a clear domain ('Salesforce Knowledge Graph') and lists four concrete operations: finding related docs, exploring namespaces, discovering service categories, and getting full context. This indicates a distinct graph-navigation resource, though it omits the 'search' action present in the schema and does not explicitly differentiate from sibling search 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 context by naming scenarios like exploring namespaces and service categories, but it gives no explicit guidance on when to prefer this tool over siblings such as sf_search or sf_semantic_search, nor does it state any exclusions. The multi-action enumeration provides some context but stops short of clear 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?

With no annotations, the description carries full responsibility. It discloses that the tool 'Returns exact numbers' and implies read-only behavior via 'Look up', but it does not mention authentication needs, error handling, or the return format in more detail. This is basic transparency but not thorough.

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 short sentences that immediately state the purpose and what the tool returns. Every word earns its place with no redundancy or filler.

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

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

For a simple one-parameter tool with no output schema, the description adequately conveys the core function and output type (exact numbers). However, it leaves minor gaps: it does not specify the response structure (e.g., JSON object) or behavior for invalid feature values, which is noticeable given the absence of 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?

The schema covers the 'feature' parameter with a descriptive list of examples (100% coverage). The description repeats some of these examples but adds no new semantic detail about parameter syntax or constraints, so the baseline of 3 applies.

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

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

The description clearly states the tool's function with a specific verb ('Look up') and resource ('Salesforce governor limits and platform constraints'). It differentiates itself from sibling tools like sf_search or sf_explain_error by focusing on numerical limits.

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: use this tool when you need exact numbers for governor limits. However, it does not explicitly state when not to use it or mention alternative tools, though the strong purpose makes the usage context obvious.

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 transparently states the read-only listing behavior and the optional filtering, which is adequate for a simple list tool. It does not mention edge cases like invalid service values, but that is not a significant omission for this operation type.

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 begins with the action and resource, immediately conveying the tool's purpose. It includes the optionality of the filter without unnecessary detail. Every word adds value.

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 simplicity of the tool (one optional parameter, no output schema, no annotations), the description is adequately complete. It explains the entire scope of functionality. It does not elaborate on response format, but the absence of an output schema lessens that need. Slight room for additional context about the nature of 'domains' but not 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 fully describes the 'service' parameter with examples ('analytics', 'commerce', 'industries', 'platform'), so schema coverage is 100%. The description's mention of 'optionally filtered by service category' adds minimal meaning beyond the schema, aligning with the baseline 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 action ('List'), the resource ('all available Salesforce documentation domains'), and the optional filtering mechanism. It effectively distinguishes this from sibling tools like sf_set_active_domains or sf_suggest_domains by focusing on enumeration.

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 for when to use this tool: to obtain a list of documentation domains, optionally narrowed by service category. It does not explicitly name alternatives or exclusions, but the context is sufficient for an agent to distinguish it from search or read 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?

With no annotations, the description carries the full transparency burden. It discloses the data sources and what kind of information is returned (object details, field types, relationships), which is useful. However, it does not mention limitations (e.g., standard objects only), pagination, or output format, leaving some behavioral aspects undefined.

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, information-dense sentence with no filler. It front-loads the core action, then adds context about the sources and output, making it optimally concise.

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

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

For a simple two-parameter lookup tool with no output schema, the description provides sufficient context: it names the sources, the type of data returned, and the scope (standard objects). It would be stronger with an explicit note about return structure, but the given info is largely adequate.

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

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

Schema descriptions cover 100% of parameters, with clear explanations for 'object' and 'field'. The description adds no parameter-specific detail beyond schema, but the schema is sufficient, so a baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Look up') and resource ('Salesforce standard object or field'), and further narrows scope by naming the exact references (Field Reference Guide, Object Reference). This clearly distinguishes it from sibling tools like sf_search or sf_graph_query, which serve different lookup/query purposes.

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 the tool is for retrieving object/field details from official Salesforce references, but it does not explicitly state when to choose this over alternatives like sf_search or sf_read_topic. No exclusions or comparisons are made, so usage guidance is only implicit.

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 states the tool reads a file and optionally extracts a section, which implies a non-destructive operation, but it doesn't disclose details like return format or behavior when the topic is not found. The description is minimal but not misleading.

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 main purpose, and each sentence adds value. It includes a usage hint and optional behavior without 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 read tool with no output schema, the description is adequate: it states the purpose, prerequisite, and optional section extraction. It does not explain the return value, but that is fairly self-evident for a read operation. Minor gaps like error handling are not critical for this 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?

The schema covers all parameters with descriptions, so the baseline is 3. The description adds little beyond what the schema already provides, only restating the optional section parameter. It does not clarify beyond the schema's examples.

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 ('Read') and the resource ('a specific Salesforce documentation topic file'). It distinguishes itself from sibling tools by specifying that it reads a specific topic, and it even references sf_search for finding the topic, which contrasts with searching.

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: 'Use sf_search first to find the domain and topic ID.' This tells the agent the prerequisite for using this tool. It doesn't explicitly discuss alternatives or when-not cases, but the context is clear enough for typical usage.

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 adds useful behavioral context (searches across all domains, respects active-domain restrictions, returns specific fields), but it does not explain match semantics, ordering, pagination, or how domain/docType filters interact with the search. For a read-only search tool this is acceptable 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?

The description is two sentences, front-loaded with the primary action and scope, and every clause adds context. It is concise without being under-specified, making it easy for an agent to scan.

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 search tool with no output schema, the description gives enough context: scope, conditional domain behavior, and return fields. It does not detail result count limits or enrichment possibilities, but those are partly covered by parameter defaults. The mention of domain restriction ties well into the sibling domain-management tools.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level meaning beyond the schema; the mention of returning titles/domains/descriptions is output-oriented rather than parameter semantics. No penalty is warranted since the schema already documents each parameter clearly.

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 ('Search') and resource ('Salesforce documentation domains'), and clarifies the return payload (titles, domains, descriptions). It does not explicitly distinguish itself from the sibling sf_semantic_search, but it does convey the cross-domain scope and the active-domain restriction behavior.

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 finding documentation topics and mentions conditional behavior ('When domain restriction is active'), but it does not explicitly state when to prefer this over sf_semantic_search or other search-like alternatives. No clear exclusions or alternative references are provided.

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 full burden. It discloses that the tool 'analyzes your query to extract entities, intent, and synonyms' and returns 'section-level matches with header paths,' which are meaningful behavioral details. It omits any side effects, but as a search tool, read-only behavior is implied. No contradictions detected.

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 sentences, front-loaded with the core purpose. Each sentence contributes new information (capability, behavioral detail, usage examples). It is concise without being terse, and no unnecessary words are present.

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 (3 parameters, no annotations, no output schema), the description provides the essential context: what it does, how it works, what it returns, and example queries. It does not explain parameter semantics beyond the schema, but the schema covers that. Overall, it is sufficiently complete for an 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 100%, so the baseline is 3. The description reinforces that the query parameter should be natural language, but does not add significant meaning beyond the schema's field descriptions and examples. The limit and domain parameters are not addressed in the description, but the schema covers them adequately.

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 a specific verb+resource: 'semantic search' with NLP query understanding, distinguishing it from regular 'sf_search'. It also describes the output ('section-level matches with header paths') and provides concrete query examples, making the tool's purpose unmistakable.

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

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

The description explicitly instructs to use this tool for natural language questions and gives examples, providing clear context. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of the highest benchmark.

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 discloses the global restriction effect and the clear behavior, but it omits persistence, override semantics, and any permission requirements. It adds useful behavioral context but does not fully carry the burden for a state-changing 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?

Three sentences, front-loaded with the active-verb opener, and no redundancy or filler. Every sentence contributes purpose, usage guidance, or clear behavior.

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 low-complexity stateful setter, the description covers the core purpose, prerequisite discovery step, and removal instructions. It is sufficient for the tool's simplicity, though persistence and override details are not addressed.

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 covers both parameters with 100% coverage. The description adds the recommendation to use sf_suggest_domains for domain IDs and mentions clear=true, but it does not go beyond the schema's existing parameter descriptions with new semantics or edge cases.

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

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

The verb 'Set' with the resource 'active domain restriction' is specific. It clarifies global scope ('all tools only return results') and distinguishes it from discovery siblings like sf_suggest_domains and sf_list_domains.

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 instructs to use sf_suggest_domains first to discover domain IDs and specifies clear=true to remove restrictions. It provides clear when-to-use context but does not state when not to use or offer alternatives beyond the discovery prerequisite.

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 transparency burden. It discloses the tool's output ('Returns domain IDs') and how those IDs are used, which is valuable behavioral context. Since this is a non-destructive suggestion tool, these details are sufficient; no rate limits, permissions, or side effects need to be mentioned.

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 core function, and every sentence earns its place. No filler or repetition of schema content.

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

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

For a single-parameter tool with no output schema and no annotations, the description is complete. It explains the input, the output, and how to use the result, leaving no significant gaps for an AI agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description doesn't add parameter-specific details beyond the schema, but the schema already includes rich examples. The tool description's reference to 'what the user is working on' aligns with the schema and adds slight context about the parameter's purpose.

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: 'Suggest relevant documentation domains based on a description of what the user is working on.' It uses a specific verb ('suggest') and resource ('documentation domains'), and distinguishes itself from siblings by noting that the returned domain IDs feed into sf_set_active_domains.

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 provides an explicit usage directive: 'Use this when the user wants to focus their search on specific Salesforce products or features.' While it doesn't name alternative tools, the context is clear and references the downstream tool (sf_set_active_domains), making the intended scenario obvious.

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