Merge pull request modelcontextprotocol#38 from modelcontextprotocol/justin/clarify-model-hints

Split out a `ModelHint` type for clarity

Author: jspahrsummers

schema/schema.json

@@ -1009,6 +1009,16 @@
             ],
             "type": "object"
         },
+        "ModelHint": {
+            "description": "Hints to use for model selection.\n\nKeys not declared here are currently left unspecified by the spec and are up\nto the client to interpret.",
+            "properties": {
+                "name": {
+                    "description": "A hint for a model name.\n\nThe client SHOULD treat this as a substring of a model name; for example:\n - `claude-3-5-sonnet` should match `claude-3-5-sonnet-20241022`\n - `sonnet` should match `claude-3-5-sonnet-20241022`, `claude-3-sonnet-20240229`, etc.\n - `claude` should match any Claude model\n\nThe client MAY also map the string to a different provider's model name or a different model family, as long as it fills a similar niche; for example:\n - `gemini-1.5-flash` could match `claude-3-haiku-20240307`",
+                    "type": "string"
+                }
+            },
+            "type": "object"
+        },
         "ModelPreferences": {
             "description": "The server's preferences for model selection, requested of the client during sampling.\n\nBecause LLMs can vary along multiple dimensions, choosing the \"best\" model is\nrarely straightforward.  Different models excel in different areas—some are\nfaster but less capable, others are more capable but more expensive, and so\non. This interface allows servers to express their priorities across multiple\ndimensions to help clients make an appropriate selection for their use case.\n\nThese preferences are always advisory. The client MAY ignore them. It is also\nup to the client to decide how to interpret these preferences and how to\nbalance them against other considerations.",
             "properties": {
@@ -1019,9 +1029,9 @@
                     "type": "number"
                 },
                 "hints": {
-                    "description": "Optional string hints to use for model selection. How these hints are\ninterpreted depends on the key(s) in each record:\n\n- If the record contains a `name` key:\n   - The client SHOULD treat this as a substring of a model name; for example:\n       - `claude-3-5-sonnet` should match `claude-3-5-sonnet-20241022`\n       - `sonnet` should match `claude-3-5-sonnet-20241022`, `claude-3-sonnet-20240229`, etc.\n       - `claude` should match any Claude model\n   - The client MAY also map the string to a different provider's model name or a different model family, as long as it fills a similar niche; for example:\n       - `gemini-1.5-flash` could match `claude-3-haiku-20240307`\n\nAll other keys are currently left unspecified by the spec and are up to the\nclient to interpret.\n\nIf multiple hints are specified, the client MUST evaluate them in order\n(such that the first match is taken).\n\nThe client SHOULD prioritize these hints over the numeric priorities, but\nMAY still use the priorities to select from ambiguous matches.",
+                    "description": "Optional hints to use for model selection.\n\nIf multiple hints are specified, the client MUST evaluate them in order\n(such that the first match is taken).\n\nThe client SHOULD prioritize these hints over the numeric priorities, but\nMAY still use the priorities to select from ambiguous matches.",
                     "items": {
-                        "$ref": "#/definitions/Record<string,string>"
+                        "$ref": "#/definitions/ModelHint"
                     },
                     "type": "array"
                 },
@@ -1337,9 +1347,6 @@
             ],
             "type": "object"
         },
-        "Record<string,string>": {
-            "type": "object"
-        },
         "Request": {
             "properties": {
                 "method": {

schema/schema.ts

@@ -806,27 +806,15 @@ export interface ImageContent {
  */
 export interface ModelPreferences {
   /**
-   * Optional string hints to use for model selection. How these hints are
-   * interpreted depends on the key(s) in each record:
-   *
-   * - If the record contains a `name` key:
-   *    - The client SHOULD treat this as a substring of a model name; for example:
-   *        - `claude-3-5-sonnet` should match `claude-3-5-sonnet-20241022`
-   *        - `sonnet` should match `claude-3-5-sonnet-20241022`, `claude-3-sonnet-20240229`, etc.
-   *        - `claude` should match any Claude model
-   *    - The client MAY also map the string to a different provider's model name or a different model family, as long as it fills a similar niche; for example:
-   *        - `gemini-1.5-flash` could match `claude-3-haiku-20240307`
-   *
-   * All other keys are currently left unspecified by the spec and are up to the
-   * client to interpret.
+   * Optional hints to use for model selection.
    *
    * If multiple hints are specified, the client MUST evaluate them in order
    * (such that the first match is taken).
    *
    * The client SHOULD prioritize these hints over the numeric priorities, but
    * MAY still use the priorities to select from ambiguous matches.
    */
-  hints?: Record<"name" | string, string>[];
+  hints?: ModelHint[];
 
   /**
    * How much to prioritize cost when selecting a model. A value of 0 means cost
@@ -862,6 +850,27 @@ export interface ModelPreferences {
   intelligencePriority?: number;
 }
 
+/**
+ * Hints to use for model selection.
+ *
+ * Keys not declared here are currently left unspecified by the spec and are up
+ * to the client to interpret.
+ */
+export interface ModelHint {
+  /**
+   * A hint for a model name.
+   * 
+   * The client SHOULD treat this as a substring of a model name; for example:
+   *  - `claude-3-5-sonnet` should match `claude-3-5-sonnet-20241022`
+   *  - `sonnet` should match `claude-3-5-sonnet-20241022`, `claude-3-sonnet-20240229`, etc.
+   *  - `claude` should match any Claude model
+   * 
+   * The client MAY also map the string to a different provider's model name or a different model family, as long as it fills a similar niche; for example:
+   *  - `gemini-1.5-flash` could match `claude-3-haiku-20240307`
+   */
+  name?: string;
+}
+
 /* Autocomplete */
 /**
  * A request from the client to the server, to ask for completion options.