Server Quality Checklist

Tool Scores

• sf_build_projectA
  3.5/5.0
  Behavior3/5

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

  Annotations provide idempotentHint=true, and description adds that it 'reports the result,' which clarifies output. However, description does not disclose potential side effects like file generation (e.g., target directory) or what exactly the result contains (e.g., success/failure, logs). With annotations covering safety, the description adds minimal context.

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

  Conciseness5/5

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

  Single sentence, no waste. All information is front-loaded and succinct. Every word serves a purpose.

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

  Completeness3/5

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

  For a simple build tool with one parameter and no output schema, the description covers the main action but omits details on failure handling, return value format, or any subsequent steps. Could be more helpful with brief mention of typical output structure.

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

  Parameters3/5

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

  Schema coverage is 100% and parameter 'project_path' has a clear description. The tool description does not add any additional meaning beyond the schema, so baseline of 3 is appropriate. No extra info on format, constraints, or examples.

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

  Purpose5/5

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

  Description clearly states the tool runs 'bal build' on a project directory and reports the result. It distinguishes from sibling tools like 'sf_deploy_project' (deploying) and 'sf_scaffold_project' (scaffolding), providing a specific verb-resource combination.

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

  Usage Guidelines2/5

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

  No guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., project must have been scaffolded), expected state before building, or when other tools like 'sf_deploy_project' would be more appropriate. Lacks explicit when-not-to-use or alternative references.

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

• sf_add_custom_objectA
  3.9/5.0
  Behavior4/5

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

  The description discloses different behaviors for standard vs custom objects (appending to types.bal) and the return value, beyond what annotations provide. However, it does not mention error conditions, duplicate handling, or verification steps, though annotations already indicate non-destructive and open-world nature.

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

  Conciseness5/5

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

  The description is three sentences with no unnecessary words, front-loaded with the core action, and efficiently covers the key distinction and output.

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

  Completeness3/5

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

  The description explains the purpose and output (resource-route snippet) but lacks detail on error scenarios, prerequisites (e.g., scaffolded project, valid Salesforce connection), and exact file locations. Given the complexity of 6 required parameters and file modification, it is moderately complete.

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

  Parameters3/5

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

  The input schema already covers all 6 parameters with descriptions; the tool description adds only marginal context (e.g., 'already-scaffolded' relating to project_path). With 100% schema coverage, baseline is 3 and the description provides no additional parameter semantics.

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

  Purpose5/5

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

  The description uses a specific verb 'Adds a new SObject' and clearly identifies the context 'to an already-scaffolded project'. It distinguishes between standard and custom objects with distinct behaviors, and uniquely defines the tool among siblings.

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

  Usage Guidelines3/5

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

  The description implies usage after project scaffolding but does not explicitly state prerequisites, exclusions, or alternatives. It lacks guidance on when not to use this tool, such as when the project is not yet scaffolded or when a different operation (e.g., describing an SObject) is more appropriate.

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

• sf_add_cdc_listenerA
  4/5.0
  Behavior3/5

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

  The description discloses behavioral traits such as reusing existing OAuth2 credentials and the stubs generated for different listener types. However, it does not discuss side effects like project file modifications, mutability, or idempotency beyond the annotations (which are neutral). More detail on what changes are made could improve transparency.

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

  Conciseness5/5

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

  The description is concise, using bullet points for clarity, and front-loaded with the main purpose. Every sentence adds value without redundancy. Efficient for an AI agent to parse.

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

  Completeness4/5

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

  Given the complexity (nested object parameter) and lack of output schema, the description sufficiently covers the three subscription modes, events behavior, and credential reuse. It could be more complete by mentioning prerequisites or error scenarios, but it provides adequate context for an agent to select and invoke the tool correctly.

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

  Parameters4/5

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

  The description adds meaning beyond the input schema by explaining the channel names for each listener type (e.g., /data/AccountChangeEvent) and that the 'events' parameter is ignored for platform events. This enriches the schema's descriptions, which already cover each parameter. The description compensates for the 50% schema description coverage by providing contextual semantics.

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

  Purpose5/5

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

  The description clearly states the tool adds an event-driven listener to an existing scaffolded project, with specific verb 'adds' and resource 'listener'. It distinguishes from sibling tools like sf_scaffold_project and sf_build_project by focusing on adding a listener to an already scaffolded project.

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

  Usage Guidelines3/5

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

  The description implies usage for existing scaffolded projects and explains the three subscription modes, but does not provide explicit guidance on when to use this tool vs alternatives or when not to use it. No exclusions or conditional contexts are mentioned.

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

• sf_list_sobjectsA
  4/5.0
  Behavior4/5

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

  Annotations indicate read-only, idempotent, and non-destructive behavior. The description adds details on the return JSON structure, including fields like total, count, offset, has_more, next_offset, and sobjects[], providing useful 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.

  Conciseness5/5

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

  The description is three sentences: purpose, features, and return structure. It is front-loaded with the core action and contains no unnecessary words.

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

  Completeness4/5

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

  The description covers the tool's purpose, features, and return format. For a filtered listing tool with full schema coverage and annotations, it is mostly complete, though it could mention error handling or prerequisites (already in schema).

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

  Parameters3/5

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

  Schema coverage is 100%, so the schema already documents all parameters. The description reiterates filtering and pagination but does not add new semantic meaning beyond what the schema provides.

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

  Purpose5/5

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

  The description clearly states the tool lists SObjects (standard and/or custom) available in the org, with filtering and pagination. This distinguishes it from sibling tools like sf_describe_sobject and sf_add_custom_object.

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

  Usage Guidelines3/5

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

  The description mentions filtering and pagination but does not explicitly guide when to use this tool versus alternatives, nor does it mention when not to use it. Usage is implied but not clarified.

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

• sf_deploy_projectA
  4.2/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint=false and destructiveHint=false, providing baseline safety info. The description adds that the service runs in the background, returns a PID for later stop via sf_stop_project, and waits for the listener to come up. This adds behavioral context 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.

  Conciseness5/5

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

  Three sentences, each earning its place: first states action, second explains port handling, third describes return values. Front-loaded with key information. No redundant or filler content.

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

  Completeness4/5

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

  Given tool complexity (2 params, no output schema), the description adequately covers purpose, outcome (started=true, PID), and linkage to stop tool. It could mention error states or prerequisites, but overall complete for its scope.

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

  Parameters4/5

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

  Schema already describes both parameters (project_path, port) with descriptions and constraints, achieving 100% coverage. The description adds that the port is passed as a configurable override and that service_url matches the listener, enhancing understanding beyond schema.

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

  Purpose5/5

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

  The description clearly states the tool starts a Ballerina service via 'bal run', passes a port, and returns started=true and a PID. It distinguishes from siblings like sf_build_project (build only) and sf_stop_project (stop).

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

  Usage Guidelines3/5

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

  There is no explicit guidance on when to use this tool vs alternatives, but the context signals show siblings like sf_build_project and sf_stop_project, and the description implies use after building. However, it lacks explicit when-not-to-use or alternative tool mentions.

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

• sf_describe_sobjectA
  4.2/5.0
  Behavior4/5

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

  Annotations show readOnly, idempotent. Description adds error details ('NOT_FOUND') and confirms return type, aligning with and extending annotations.

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

  Conciseness5/5

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

  Extremely concise: two sentences and error list, with no extraneous content.

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

  Completeness4/5

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

  Adequately describes the purpose and return value; no output schema but the nature of a describe tool is clear. Errors are documented. Complete enough for an AI agent.

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

  Parameters3/5

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

  Schema coverage is 100%, so the description doesn't need to add param details. Description indirectly mentions object_name but adds minimal extra meaning.

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

  Purpose5/5

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

  The description clearly states it returns full field-level metadata for a specific SObject, distinguishing it from sibling tools like sf_list_sobjects.

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

  Usage Guidelines4/5

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

  Provides explicit use case: inspect fields before generating Ballerina records. Does not specify 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.

• sf_import_postman_credentialsA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds useful behavioral context: it reads a file, returns credentials, and optionally validates with a live API call via the 'validate' parameter. This goes beyond what annotations provide, though the core safety profile is already 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.

  Conciseness4/5

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

  The description is two paragraphs with clear structure: first sentence states primary purpose, then conditional logic, then final outcome. It is concise with no unnecessary words, but could be slightly tighter by merging sentences.

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

  Completeness5/5

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

  Despite no output schema, the description explains the return value ('ready_for_quickstart' block for sf_quickstart). For a tool with only 2 parameters, the description covers all relevant aspects: input path, validation behavior, and outcome. It is fully complete given the tool's simplicity.

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

  Parameters3/5

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

  Schema coverage is 100% and parameter descriptions exist. The description adds context about the 'validate' parameter (makes a live call) and mentions path format for 'postman_file', but this largely overlaps with schema descriptions. Baseline 3 is appropriate as the description adds marginal value beyond detailed schema.

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

  Purpose5/5

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

  The description uses specific verbs ('Reads', 'extracts') and clearly identifies the resource (Postman collection) and the extracted credentials. It distinguishes from siblings by mentioning sf_generate_postman_collection as a source and sf_quickstart as the consumer, also referencing sf_get_token_password_flow as an alternative path.

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

  Usage Guidelines4/5

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

  The description provides clear context: use this tool to avoid manual credential typing. It explains conditional behavior (refresh token vs username/password) and directs to sf_get_token_password_flow when needed. However, it does not explicitly state when not to use this tool or list other alternatives beyond the one reference.

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

• sf_setup_guideA
  4.2/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds little beyond stating it returns a guide. No behavioral details beyond content are provided.

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

  Conciseness5/5

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

  Three sentences pack purpose, content, and usage triggers with no fluff. Front-loaded with the key fact 'returns a step-by-step guide'.

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

  Completeness4/5

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

  For a simple guide tool with one optional boolean and no output schema, the description covers when and what. Minor gap: does not specify output format (e.g., text, JSON), but acceptable given simplicity.

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

  Parameters3/5

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

  Schema coverage is 100%, so the schema fully explains the single 'sandbox' parameter. The description does not add any additional meaning about the parameter.

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

  Purpose5/5

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

  The description clearly states it returns a step-by-step guide for first-time users, listing specific content. It distinguishes itself from sibling tools which are actual operational actions (e.g., getting auth URL).

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

  Usage Guidelines5/5

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

  Explicitly tells when to call: when user says 'I'm new' / 'where do I start' / 'how do I get credentials'. Also suggests which tools to call next, aiding workflow.

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

• sf_validate_connectionA
  4.2/5.0
  Behavior4/5

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

  Annotations already indicate read-only, non-destructive, idempotent, and open-world hints. The description adds that it makes a live API call and returns specific fields (connected, org_id, etc.), which enhances transparency. 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.

  Conciseness5/5

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

  The description is extremely concise: one sentence for purpose and usage, then a bullet list of return values. Every sentence earns its place. No fluff.

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

  Completeness4/5

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

  Given full schema coverage and annotations, the description covers purpose, usage, and return values. It does not address error cases (e.g., what if credentials invalid?), but the return structure implies connected: boolean. Overall, adequate for a validation tool.

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

  Parameters3/5

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

  Input schema has 100% coverage with full descriptions for all four parameters. The description does not add any additional parameter-level meaning; it only describes the return values. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool tests Salesforce credentials with a live API call. The title 'Validate Salesforce Connection' and the first sentence specify the verb and resource. Among siblings like sf_get_oauth_auth_url and sf_exchange_oauth_code, this tool is distinct as a validation step.

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

  Usage Guidelines4/5

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

  The description explicitly recommends using this tool 'before scaffolding a project to confirm credentials work,' providing clear context. It does not elaborate on when not to use it or list alternatives, but the guidance is sufficiently clear for an agent.

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

• sf_scaffold_projectA
  4.3/5.0
  Behavior4/5

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

  Annotations show readOnlyHint=false and destructiveHint=false; description adds that for custom objects it 'describes from your org and typed in types.bal' and 'fail loudly if missing'. This is transparent about behavior beyond annotations, though could detail project file structure.

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

  Conciseness4/5

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

  Well-structured with pre-conditions and clear sections. However, some sentences (e.g., about standard vs custom) could be integrated into parameter descriptions. Still, front-loaded purpose and efficient overall.

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

  Completeness4/5

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

  Given 11 parameters and no output schema, description covers purpose, usage guidance, pre-conditions, and parameter hints adequately. Lacks explicit return value documentation but acceptable for a scaffolding action.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents all 11 parameters thoroughly. Description adds marginal context (e.g., 'custom objects fail loudly'), but does not significantly enhance understanding beyond schema.

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

  Purpose5/5

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

  The description clearly states it 'Creates a Ballerina integration project' and distinguishes from sibling 'sf_quickstart' by noting that quickstart wraps this plus credential validation and build step. The verb+resource combination is specific and unambiguous.

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

  Usage Guidelines5/5

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

  Explicitly advises 'For most users, prefer sf_quickstart' and lists pre-conditions (bal CLI, target objects exist). This provides clear when-to-use guidance and differentiates from alternatives.

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

• sf_check_prerequisitesA
  4.4/5.0
  Behavior4/5

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

  Adds context beyond annotations: specifies what the tool checks (installation and version) and implies no side effects. 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.

  Conciseness5/5

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

  Two sentences, front-loaded with primary action, no wasted words. Efficient and clear.

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

  Completeness4/5

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

  For a zero-parameter tool with no output schema, the description covers the main purpose. Slightly incomplete about error behavior if CLI missing, but still adequate.

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

  Parameters4/5

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

  No parameters exist; baseline of 4 applies as description does not need to explain parameters.

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

  Purpose5/5

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

  Description uses specific verb 'Verifies' and identifies exact resource 'bal CLI installed and version'. Clearly distinguishes from sibling tools which focus on Salesforce operations.

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

  Usage Guidelines4/5

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

  Explicitly advises to run this first before scaffolding, providing clear usage context. No mention of when not to use, but the guidance is direct.

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

• sf_get_oauth_auth_urlA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds context that this is a URL generation step requiring user interaction and describes the follow-up redirect and code parameter, enhancing understanding of behavior 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.

  Conciseness5/5

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

  Three sentences: first defines purpose, second details the flow, third optional switch. Front-loaded, no redundancy, every sentence adds value.

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

  Completeness4/5

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

  Tool has 3 params, no output schema. Description covers flow and next steps, but could briefly mention that the generated URL includes the client_id and redirect_uri. Overall sufficiently complete for an auth URL generation tool.

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

  Parameters4/5

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

  Input schema has 100% coverage. Description adds real-world meaning: explains sandbox parameter effect, role of redirect_uri in flow, and identifies sf_client_id as Consumer Key, providing practical usage context.

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

  Purpose5/5

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

  The description clearly states the tool generates the Salesforce OAuth2 authorization URL for a Connected App, with specific verb and resource. It differentiates from siblings by naming the next step (sf_exchange_oauth_code) and implying the code flow, not other auth methods.

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

  Usage Guidelines4/5

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

  The description outlines the complete flow: generate URL → browser approval → code exchange, indicating when to use this tool. However, it does not explicitly exclude alternative flows like password grant (sf_get_token_password_flow), leaving minor ambiguity.

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

• sf_get_token_password_flowA
  4.4/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds context about requiring a Connected App configuration, security token handling, and return values. It does not contradict annotations and provides useful behavioral details 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.

  Conciseness5/5

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

  The description is concise, front-loaded with the core purpose, and structured with a bullet list for requirements. Every sentence adds value without unnecessary wording.

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

  Completeness4/5

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

  Given the absence of an output schema, the description mentions return values (refresh_token and ready_for_quickstart block) and prerequisites. It covers most essential aspects for invoking the tool but omits error handling or failure scenarios.

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

  Parameters4/5

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

  Schema coverage is 100% with descriptions for all 5 parameters. The description adds extra semantics by explaining how to append security token to password and that sf_base_url auto-detects sandbox. This enhances the schema's information.

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

  Purpose5/5

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

  The description clearly states the verb 'obtains' and the resource 'Salesforce OAuth2 tokens using the username+password grant'. It distinguishes from sibling tools like sf_exchange_oauth_code and sf_get_oauth_auth_url by explicitly mentioning 'no browser, no auth-code redirect required'.

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

  Usage Guidelines4/5

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

  The description provides explicit requirements for the Connected App setup and password security token appending. It mentions the return of refresh_token and a block for sf_quickstart, but does not explicitly list alternative tools or when not to use this flow.

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

• sf_write_config_tomlA
  4.4/5.0
  Behavior5/5

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

  Beyond the idempotentHint and non-destructive annotations, the description adds that the file is written with mode 0600 (security) and that sandbox is auto-detected, giving useful behavioral context.

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

  Conciseness5/5

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

  Three concise, front-loaded sentences with no unnecessary words; every sentence adds value.

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

  Completeness4/5

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

  For a write tool with no output schema, the description covers purpose and key behaviors, but could optionally mention what happens on success or error conditions.

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

  Parameters3/5

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

  The input schema already covers all parameters with descriptions, so the description adds minimal extra semantic value, merely echoing the credentials purpose and sandbox detection.

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

  Purpose5/5

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

  The description clearly states the tool overwrites Config.toml with fresh Salesforce OAuth2 credentials, distinguishing it from sibling tools that perform validation, URL generation, or other operations.

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

  Usage Guidelines4/5

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

  The description mentions 'useful for rotation' and notes sandbox auto-detection, providing context for when to use, though it does not explicitly state when not to use or list alternatives.

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

• sf_stop_projectA
  4.5/5.0
  Behavior5/5

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

  Annotations indicate destructive and idempotent. Description adds that only tracked PIDs from the current session can be stopped, with safety rationale. This provides valuable context 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.

  Conciseness5/5

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

  Two sentences, front-loaded with the main action, every sentence adds value. No unnecessary words.

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

  Completeness5/5

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

  For a simple tool with one param and no output schema, the description covers purpose, usage constraints, safety, and dependency on sf_deploy_project. Completely adequate for correct selection and invocation.

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

  Parameters3/5

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

  Schema coverage is 100% and description adds little new info beyond what is already in the schema's parameter description. The tool description reiterates the PID's origin but does not significantly enhance semantic understanding.

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

  Purpose5/5

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

  Description clearly states it stops a running Ballerina service started by sf_deploy_project. The verb 'stops' and resource 'bal run process' are specific, and it distinguishes from sibling tools like sf_deploy_project.

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

  Usage Guidelines4/5

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

  Description tells when to use (only for PIDs from sf_deploy_project) and explicitly states safety restrictions. It implies not for arbitrary host PIDs, but does not explicitly list alternatives.

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

• sf_exchange_oauth_codeA
  4.7/5.0
  Behavior5/5

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

  Annotations provide readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true. The description goes beyond annotations by disclosing that the access_token is masked in output (keeping it out of transcripts) and that refresh_token is long-lived. Error scenarios are detailed with actionable advice. No contradiction with annotations.

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

  Conciseness5/5

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

  The description is succinct with no superfluous text. Key sections are clearly separated: main action, parameter note, output details, error handling. Every sentence contributes essential information.

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

  Completeness5/5

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

  Given the complexity of OAuth token exchange, the description adequately covers the purpose, all parameters, return values (refresh_token, instance_url), behavior (access_token masked), and error cases. No output schema exists, but the description compensates. The agent can confidently use this tool.

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

  Parameters4/5

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

  Schema coverage is 100%, but the description adds meaning: it clarifies the sandbox parameter's effect (test.salesforce.com vs login.salesforce.com), implies that redirect_uri must match the one used previously, and explains that the code comes from the OAuth redirect. This enriches the bare schema descriptions.

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

  Purpose5/5

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

  The description clearly states the tool exchanges an OAuth2 authorization code for tokens, distinguishing it from sibling tools like sf_get_oauth_auth_url and sf_get_token_password_flow. The verb 'exchange' and resource 'authorization code' are specific and unambiguous.

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

  Usage Guidelines4/5

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

  The description explains when to use it (after obtaining the code) and provides error-specific guidance (e.g., re-run sf_get_oauth_auth_url for invalid_grant). It also mentions the sandbox parameter. However, it does not explicitly contrast with the password flow or other authentication tools, leaving some implicit use-case differentiation.

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

• sf_generate_postman_collectionA
  4.8/5.0
  Behavior5/5

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

  Detailed disclosure of automation: auto-obtains refresh token, bakes credentials, saves to disk, and returns a block. Annotations indicate non-destructive and open world, which aligns with the description. 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.

  Conciseness4/5

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

  Well-structured with a clear lead sentence and bullet points for contents. Every sentence adds value, though could be slightly more streamlined.

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

  Completeness5/5

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

  Covers the entire process, components of the generated collection, and return value. Completes the picture for a complex tool with no output schema.

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

  Parameters4/5

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

  Schema already describes all parameters with 100% coverage, and the description adds extra context (e.g., appending security token for password, default output path). Provides value beyond the schema.

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

  Purpose5/5

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

  The description clearly states it creates a complete Postman collection for Salesforce, listing contents and connecting to sibling tools like sf_quickstart and sf_import_postman_credentials. It distinguishes itself by being the recommended first step.

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

  Usage Guidelines5/5

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

  Explicitly states it is the recommended first step and provides clear next steps: call sf_quickstart immediately or use sf_import_postman_credentials later. No ambiguity about when to use.

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

• sf_quickstartA
  4.9/5.0
  Behavior5/5

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

  Discloses all steps (validation, auto-detection, scaffolding, optional build) with side-effect details (e.g., file creation, compilation time). Annotations already indicate non-read-only and non-destructive, so the description adds context about what the tool does 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.

  Conciseness5/5

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

  The description is well-structured with numbered steps and bullet points for defaults. It is concise, front-loading the core purpose, and every sentence serves a purpose without redundancy.

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

  Completeness5/5

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

  Given the tool's complexity (12 parameters, no output schema, open world), the description is complete. It explains default behavior, the flow, and when to use this tool versus alternatives, making it fully actionable for an agent.

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

  Parameters4/5

  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 value by listing sensible defaults and explaining the sandbox auto-detection override. It also provides context for the cdc_listeners array structure, going beyond the schema descriptions.

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

  Purpose5/5

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

  The description clearly states it performs an end-to-end setup in a single call, listing step-by-step actions (validate, detect, scaffold, optional build). It distinguishes itself as the recommended entry point among sibling tools, mentioning when to use alternatives like sf_setup_guide.

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

  Usage Guidelines5/5

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

  Explicitly says 'most users only need to call this tool' and advises calling sf_setup_guide first if credentials are missing. The description also implies this is the starting point, with other tools for later customization.

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