Server Quality Checklist

Tool Scores

• scp_check_authorizationC
  2.9/5.0
  Behavior2/5

  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 states the tool checks authorization status but does not explain what 'authorized' entails, such as required permissions, authentication methods, or the response format. This leaves significant gaps in understanding the tool's behavior, warranting a score of 2.

  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 a single, efficient sentence: 'Check if authorized with a merchant domain.' It is front-loaded and wastes no words, making it easy to parse. However, it could be slightly more informative without sacrificing brevity, so it scores a 4.

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

  Completeness2/5

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

  Given the lack of annotations and output schema, the description is incomplete for a tool that checks authorization status. It does not explain what 'authorized' means in this context, the expected return values, or error conditions. For a tool with potential security implications, this is inadequate, resulting in a score of 2.

  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 has 100% description coverage, with the 'domain' parameter clearly documented as 'Merchant domain.' The description adds no additional meaning beyond this, as it does not elaborate on the parameter's usage or constraints. Given the high schema coverage, the baseline score of 3 is appropriate.

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

  Purpose4/5

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

  The description clearly states the tool's purpose: 'Check if authorized with a merchant domain.' It specifies the verb ('Check') and resource ('authorized with a merchant domain'), making the action understandable. However, it does not differentiate this tool from siblings like 'scp_authorize' or 'scp_revoke_authorization,' which limits its score to 4.

  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?

  The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, such as needing prior authorization, or suggest when to choose it over siblings like 'scp_authorize' for authorization actions. This lack of contextual direction results in a score of 2.

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

• scp_discoverC
  2.9/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden. It mentions DNS-based discovery but doesn't disclose behavioral traits like whether this is a read-only operation, what happens on failure, if there are rate limits, or what format the discovered endpoint information takes. For a discovery tool with zero annotation coverage, this leaves critical operational context unspecified.

  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 a single, efficient sentence that communicates the core functionality without unnecessary words. It's appropriately sized for a simple discovery tool and front-loads the essential information. Every word earns its place.

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

  Completeness2/5

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

  Given the tool's role in an SCP ecosystem with multiple sibling tools, the description is insufficiently complete. It doesn't explain how the discovered endpoint integrates with other tools (like scp_authorize), what the output contains, or why discovery is needed. With no annotations and no output schema, the description should provide more operational context for effective agent use.

  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% with one parameter ('domain' described as 'Merchant domain'), so the schema already documents the parameter adequately. The description doesn't add meaningful semantic context beyond what the schema provides, such as domain format requirements or DNS lookup specifics. Baseline 3 is appropriate when schema does the heavy lifting.

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

  Purpose4/5

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

  The description clearly states the action ('Discover') and target ('SCP endpoint for a merchant domain via DNS'), making the purpose understandable. It distinguishes from siblings by focusing on endpoint discovery rather than authorization, intent management, or data retrieval operations. However, it doesn't explicitly contrast with specific sibling tools.

  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?

  The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a merchant domain before other operations), when discovery is necessary, or what to do with the discovered endpoint. With multiple sibling tools for authorization and data operations, this lack of contextual guidance is a significant gap.

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

• scp_revoke_authorizationC
  2.9/5.0
  Behavior2/5

  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 states the action is to 'revoke authorization', implying a destructive mutation, but doesn't clarify if this is permanent, reversible, requires specific permissions, or has side effects (e.g., impacting related intents or orders). This leaves significant gaps in understanding the tool's behavior.

  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 a single, clear sentence with no wasted words. It's front-loaded with the core action and target, making it efficient and easy to parse. Every part of the sentence contributes directly to understanding the tool's purpose.

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

  Completeness2/5

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

  For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't address what happens after revocation (e.g., success/failure responses, error conditions, or effects on sibling tools like orders or intents). Given the complexity implied by 'revoke' and the lack of structured data, more context is needed for effective use.

  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 has 100% description coverage, with the 'domain' parameter clearly documented as 'Merchant domain'. The description doesn't add any extra meaning beyond this, such as format examples or domain validation rules. Given the high schema coverage, a baseline score of 3 is appropriate as the schema handles the parameter documentation adequately.

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

  Purpose4/5

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

  The description clearly states the action ('revoke authorization') and the target ('with a merchant domain'), which is specific and unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'scp_check_authorization' or 'scp_authorize', which would require mentioning what makes revocation distinct from checking or granting authorization.

  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?

  The description provides no guidance on when to use this tool versus alternatives. For example, it doesn't specify if this should be used after checking authorization status with 'scp_check_authorization' or as an alternative to other tools. There's no mention of prerequisites, exclusions, or contextual cues for invocation.

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

• scp_get_intentsB
  3.2/5.0
  Behavior2/5

  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 mentions the authorization prerequisite, which is useful, but doesn't cover other aspects like rate limits, error handling, pagination, or what 'shopping intents' entail. For a read operation with no annotation coverage, this leaves significant gaps in understanding the tool's behavior.

  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 two sentences, front-loaded with the core purpose and followed by a key prerequisite. Every word serves a purpose, with no redundancy or unnecessary elaboration, making it highly efficient and well-structured.

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

  Completeness2/5

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

  Given the tool's complexity (retrieving merchant data with filtering), lack of annotations, and no output schema, the description is incomplete. It mentions authorization but omits details on return format, error cases, or how 'shopping intents' are defined. This leaves the agent with insufficient context for reliable use.

  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%, meaning all parameters are documented in the schema. The description doesn't add any parameter-specific details beyond what's in the schema (e.g., it doesn't explain 'domain' authorization further or 'status' values). With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but also doesn't detract.

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

  Purpose4/5

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

  The description clearly states the action ('Get shopping intents') and resource ('from a merchant'), making the purpose understandable. However, it doesn't explicitly differentiate this tool from sibling tools like 'scp_get_offers' or 'scp_get_orders', which might also retrieve merchant data, so it lacks full sibling distinction.

  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 provides some usage context by stating 'Domain must be authorized first', implying a prerequisite. However, it doesn't specify when to use this tool versus alternatives like 'scp_get_offers' or 'scp_get_orders', nor does it mention any exclusions or detailed scenarios for use.

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

• scp_update_intentB
  3.2/5.0
  Behavior2/5

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

  With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the authorization requirement ('Domain must be authorized with intent:write scope'), which is useful context about permissions. However, it doesn't describe what 'update' entails (e.g., partial vs. full updates, validation rules, error handling, or side effects), leaving significant gaps 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.

  Conciseness5/5

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

  The description is a single, efficient sentence that front-loads the core action ('Update an existing shopping intent') and includes essential authorization context. Every word earns its place with zero waste, making it highly concise and well-structured.

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

  Completeness2/5

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

  For a mutation tool with no annotations and no output schema, the description is incomplete. It covers the authorization prerequisite but lacks details on behavioral aspects (e.g., what happens on update, response format, error conditions). Given the complexity of updating an intent with multiple parameters, more context is needed to adequately guide an 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 description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema (e.g., it doesn't explain relationships between parameters or provide examples). This meets the baseline of 3 when schema coverage is high.

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

  Purpose4/5

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

  The description clearly states the verb ('Update') and resource ('existing shopping intent'), making the purpose unambiguous. It distinguishes from siblings like scp_create_intent by specifying 'existing' intent, but doesn't explicitly differentiate from other potential update operations. The domain authorization requirement adds specificity.

  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 provides some usage context by stating 'Domain must be authorized with intent:write scope,' which implies when to use (after authorization) and prerequisites. However, it doesn't explicitly guide when to choose this tool versus alternatives like scp_create_intent or how it differs from other update-related operations. The 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.

• scp_create_intentA
  3.5/5.0
  Behavior2/5

  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 mentions the authorization scope requirement, which is useful context. However, it lacks details on what 'create' entails (e.g., is it idempotent, does it return an ID, what happens on failure, rate limits, or permissions beyond scope). For a creation tool with no annotations, this leaves significant gaps in understanding its behavior.

  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 a single, efficient sentence that front-loads the core purpose and includes the critical scope requirement. There is no wasted text, and it's structured to convey essential information without redundancy.

  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?

  Given no annotations and no output schema, the description is moderately complete. It covers the purpose and a key prerequisite (authorization scope), but lacks details on behavioral traits, error handling, or return values. For a creation tool with 6 parameters and no structured safety hints, it should provide more context about what 'create' entails and the outcome.

  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 fully documents all 6 parameters. The description adds no additional parameter information beyond implying the 'domain' parameter relates to authorization. Since the schema does the heavy lifting, the baseline score of 3 is appropriate, as the description doesn't add meaningful semantics beyond what's already in the schema.

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

  Purpose4/5

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

  The description clearly states the action ('Create a new shopping intent') and the target ('with a merchant'), which is specific and actionable. It distinguishes from siblings like scp_get_intents (read vs. create) and scp_update_intent (create vs. update). However, it doesn't fully explain what a 'shopping intent' entails beyond the scope requirement.

  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 context for when to use this tool: 'Domain must be authorized with intent:create scope.' This gives a clear prerequisite. It doesn't explicitly state when not to use it or name alternatives, but the scope requirement implies usage is conditional on authorization.

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

• scp_get_loyaltyA
  3.5/5.0
  Behavior2/5

  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 mentions the authorization prerequisite, which adds some context, but it does not describe other behavioral traits such as what data is returned (e.g., format of loyalty status/points), error handling, rate limits, or authentication needs beyond the implied authorization. For a tool with zero annotation coverage, this is a significant gap in transparency.

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

  Conciseness5/5

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

  The description is appropriately sized and front-loaded with two concise sentences: the first states the purpose, and the second provides the key usage guideline. Every sentence earns its place by delivering essential information without waste, making it highly efficient and well-structured.

  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?

  Given the tool's complexity (simple retrieval with one parameter), no annotations, and no output schema, the description is partially complete. It covers the purpose and a key prerequisite, but it lacks details on return values, error cases, or behavioral nuances. Without an output schema, the description should ideally explain what 'loyalty status and points' entails, but it does not, leaving gaps in completeness.

  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 has 100% description coverage, with the 'domain' parameter documented as 'Merchant domain.' The description does not add any additional meaning beyond this, as it only references 'domain' in the context of authorization. Since the schema already fully describes the parameter, the baseline score of 3 is appropriate, as the description does not compensate but also does not detract.

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

  Purpose4/5

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

  The description clearly states the tool's purpose: 'Get loyalty status and points from a merchant.' It specifies the action ('Get'), resource ('loyalty status and points'), and target ('merchant'), which is specific and informative. However, it does not explicitly differentiate this tool from sibling tools like 'scp_get_offers' or 'scp_get_orders', which might also retrieve merchant-related data, so it falls short of a perfect score.

  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 for usage with the statement: 'Domain must be authorized first.' This implies a prerequisite (authorization via tools like 'scp_authorize') and helps guide when to use this tool. However, it does not explicitly mention when not to use it or name alternatives (e.g., vs. 'scp_get_offers'), so it lacks full explicit guidance.

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

• scp_get_offersA
  3.5/5.0
  Behavior2/5

  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 mentions the authorization prerequisite, which adds some context, but does not cover other important traits such as whether this is a read-only operation, potential rate limits, error handling, or what the return format looks like. For a tool with no annotations, this leaves significant gaps in understanding its behavior.

  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 two sentences, front-loaded with the main purpose and followed by a prerequisite. Every sentence earns its place by providing essential information without redundancy or fluff, making it efficient and well-structured.

  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?

  Given no annotations and no output schema, the description is incomplete for a tool that likely returns data (offers). It covers the purpose and a key prerequisite but lacks details on return values, error cases, or behavioral nuances. However, the schema coverage is high, and the description is concise, making it minimally adequate but with clear gaps.

  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 both parameters (domain and active_only) adequately. The description adds minimal value beyond the schema by implying the domain parameter's role in authorization, but does not provide additional syntax or format details. This meets the baseline for high schema coverage.

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

  Purpose4/5

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

  The description clearly states the verb 'Get' and the resource 'active personalized offers from a merchant', specifying what the tool does. It distinguishes from siblings like scp_get_intents or scp_get_orders by focusing on offers, but does not explicitly contrast with them. The purpose is specific and actionable, though not fully differentiated from all siblings.

  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 for when to use this tool by stating 'Domain must be authorized first', implying a prerequisite. It does not explicitly mention when not to use it or name alternatives among siblings, but the context is sufficient for basic usage guidance without being misleading.

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

• scp_get_preferencesA
  3.5/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden. It mentions the authorization requirement, which is useful behavioral context. However, it doesn't disclose other traits like whether this is a read-only operation, potential rate limits, error conditions, or what the return format looks like (e.g., JSON structure). For a tool with zero annotation coverage, this leaves significant gaps.

  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 concise sentences with zero waste: the first states the purpose with examples, and the second provides a critical prerequisite. Every word earns its place, and the information is front-loaded appropriately.

  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?

  Given no annotations and no output schema, the description is minimally complete for a simple read operation. It covers the purpose and a key prerequisite, but lacks details on return values, error handling, or behavioral nuances that would be helpful for an agent invoking this 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?

  Schema description coverage is 100%, so the schema already documents the single 'domain' parameter. The description adds marginal value by reinforcing that it's a 'Merchant domain' and tying it to the authorization context, but doesn't provide additional syntax or format details beyond what the schema provides.

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

  Purpose4/5

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

  The description clearly states the verb 'Get' and resource 'saved customer preferences' with specific examples (sizes, styles, addresses) and source (from a merchant). It distinguishes from siblings like scp_get_orders or scp_get_offers by focusing on preferences, but doesn't explicitly contrast them.

  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?

  It provides clear context with the prerequisite 'Domain must be authorized first', which implicitly suggests using scp_authorize or scp_check_authorization first. However, it doesn't explicitly name alternatives or specify when-not-to-use scenarios beyond the authorization requirement.

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

• scp_get_ordersA
  3.7/5.0
  Behavior3/5

  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 authorization requirement, which is valuable context about access control. However, it doesn't describe other important behaviors like pagination handling (implied by limit/offset but not explained), rate limits, error conditions, or what format the order history returns. For a tool with 4 parameters and no output schema, more behavioral context would be helpful.

  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 with just two sentences that each serve a clear purpose: the first states the core functionality, and the second provides critical usage context. There's zero wasted language, and the most important information (what the tool does) comes first. This is an excellent example of efficient documentation.

  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?

  Given the tool has 4 parameters, no annotations, and no output schema, the description provides adequate but incomplete context. The authorization prerequisite is valuable, but missing details about return format, pagination behavior, error handling, and rate limits leave gaps. For a data retrieval tool with filtering capabilities, more complete context would help the agent understand what to expect from the operation.

  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 schema description coverage is 100%, so all parameters are well-documented in the schema itself. The description doesn't add any additional parameter information beyond what's already in the schema descriptions. It mentions the domain parameter indirectly through the authorization requirement, but this doesn't enhance the parameter semantics beyond the schema's documentation. The baseline score of 3 is appropriate when the schema does the heavy lifting.

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

  Purpose4/5

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

  The description clearly states the action ('Get order history') and target resource ('from a merchant'), making the purpose immediately understandable. It distinguishes this tool from siblings like scp_get_intents or scp_get_offers by specifying it retrieves order data rather than other merchant information. However, it doesn't specify whether this returns all historical orders or recent ones, which could help further differentiate from potential future tools.

  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 about when to use this tool by stating 'Domain must be authorized first,' which references the scp_authorize sibling tool. This establishes a prerequisite relationship. However, it doesn't explicitly mention when NOT to use this tool or provide alternatives for similar queries, such as when to use scp_get_intents instead for different merchant data.

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

• scp_authorizeA
  4.3/5.0
  Behavior4/5

  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 effectively describes critical behavioral traits: the prerequisite call to scp_discover, the requirement to ask for a real email address (not placeholders), and the instruction to wait for user response. However, it lacks details on rate limits, error handling, or what happens after authorization (e.g., token storage).

  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 appropriately sized and front-loaded with critical prerequisites and purpose. Every sentence earns its place: the first covers prerequisites, the second states the core action, and the third provides essential user interaction guidance. However, the email instruction is somewhat verbose and could be more streamlined.

  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 no annotations and no output schema, the description does well to cover prerequisites, purpose, and user interaction requirements. It adequately explains the tool's role in the SCP flow. However, it lacks details on return values (e.g., what authorization success looks like) and doesn't mention potential side effects or error conditions, leaving some gaps for a mutation 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?

  Schema description coverage is 100%, providing full parameter documentation. The description adds minimal value beyond the schema: it reinforces the email requirement ('REAL email address') and mentions scopes best practice ('request all needed scopes upfront'), but doesn't explain parameter interactions or provide additional semantic context. Baseline 3 is appropriate given high schema coverage.

  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 specific action ('Authorize access to a merchant's customer context via SCP') and resource ('customer context'), distinguishing it from siblings like scp_check_authorization (verification) or scp_revoke_authorization (removal). It explicitly mentions this must be called before accessing customer data, establishing its unique role in the authorization flow.

  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?

  The description provides explicit when-to-use guidance: 'BEFORE USING THIS ENSURE THE DOMAIN SUPPORTS SCP BY CALLING scp_discover FIRST' and 'Must be called before accessing any customer data.' It also implicitly suggests alternatives by naming scp_discover as a prerequisite and distinguishing from other data-access tools in the sibling list.

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