Skip to main content
Glama

profile_project

Profile a running Godot project to measure GDScript function costs, FPS, and frame timing; optionally capture CPU/GPU render stages and a timeline to locate slow frames.

Instructions

Profile a window: GDScript function costs, fps, monitors; visual adds CPU/GPU ms per render stage, timeline both over time. Requires run_project with profiling: true. Blocks for seconds (default 5, max 30; longer: start_profiler). Times are elapsed, not CPU; never sum totalMs (rows overlap). Returns: warnings first, projectPath, complete, fps, slowFrames, rows, frame, servers, worstFrame, monitors, visual, timeline. Errors if profiling is off, a capture is open or the game exits mid-window.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "profile_project"
  }
}

Input Schema

NameRequiredDescriptionDefault
topNoHow many functions to return, 1..100 (default: 20). Also caps visual.areas when the capture recorded render stages.
sortNoRank by own time ("selfMs", default), inclusive time ("totalMs"), or invocation count ("calls").
trackNoUp to 4 NodePath:property values the game samples during the capture (every 250 ms, or half the interval when shorter), placed on the timeline by frame number, e.g. "/root/Main/Player:global_position" - where the player was when frames got slow. Implies timeline. Uses the bridge: drive the game between start_profiler and stop_profiler, not in parallel with profile_project. Collected only while the session that started the capture is current.
visualNoAlso record the editor's Visual Profiler: CPU and GPU milliseconds per render stage (culling, shadows, opaque pass, canvas, ...) in `visual` (default: false). GPU times are null on GLES/web builds of the Compatibility renderer, which time no GPU work; `visual.gpuTimed` is false and a warning says so. A frame holds 256 render markers by default; a scene that needs more makes the engine log an error per lost marker, slowing the game, so the capture switches visual off and its warnings say how to raise the limit.
secondsNoCapture duration in seconds, greater than 0 and at most 30 (default: 5). The call answers only when the window has closed, and with its waits can take up to 58 s, which the limit keeps under a client's 60 s request timeout. Time spent waiting for the session queue counts against that: a call whose wait plus its worst case would pass 60 s is refused with nothing sent. For a longer capture use start_profiler (up to 60 s) and stop_profiler.
timelineNoAlso record the capture over time in `timeline.buckets`: per interval the fps, frameMs avg/max, process/physics/script ms, slowFrames, draw calls, render CPU/GPU ms (with visual) and the heaviest functions, server calls or render stages (`top`, named once in `timeline.items`) - where and when frames got slow (default: false). timelineMs, timelineTop, timelineBuckets and track turn it on by themselves; false beside any is rejected.
targetFpsNoFrame rate to hold the game to (default: 60). slowFrames counts frames whose frameMs exceeds 1000/targetFps, over the capture and per timeline interval. Under vsync every frame lasts the refresh interval: disable vsync, or set targetFps a few percent below the refresh rate.
timelineMsNoTimeline interval in milliseconds, 250..5000 (default: 500). Records at most about 60 intervals (60 s: 1000 ms) and the reply merges them down to timelineBuckets. Implies timeline.
timelineTopNoHeaviest functions, server calls or render stages listed per timeline interval, 0..10 (default: 3). 0 leaves `top` empty. Implies timeline.
captureLimitNoRows the engine puts in each frame packet, 16..512 (default: 512). Godot selects them by inclusive time, so a lower limit hides cheap functions and sets limitReached.
timelineBucketsNoMost intervals the timeline reply holds, 4..60 (default: 20). A capture recorded in more is merged: adjacent intervals combine (counts and times add up, maxima stay) and `timeline.bucketMs` reports the width. Implies timeline.

Output Schema

NameRequiredDescriptionDefault
fpsYes
rowsYes
sortYes
frameYes
framesYes
visualYes
secondsYes
serversYes
completeYes
monitorsYes
timelineYes
warningsNo
frameGapsYes
lastFrameYes
targetFpsYes
firstFrameYes
slowFramesYes
worstFrameYes
projectPathYes
captureLimitYes
limitReachedYes
framesReceivedYes
functionsReceivedYes
undecodablePacketsYes
unresolvedFunctionsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed28 schema fields changedv4.0.1
    • addedInput schema / properties / captureLimit / maximum
      Added value: +512
    • addedInput schema / properties / captureLimit / minimum
      Added value: +16
    • changedInput schema / properties / captureLimit / type
      Previous value: -"number"New value: +"integer"
    • changedInput schema / properties / seconds / description
      Previous value: -"Capture duration in seconds, greater than 0 and at most 60 (default: 5)."New value: +"Capture duration in seconds, greater than 0 and at most 30 (default: 5). The call answers only when the window has closed, and with its waits can take up to 58 s, which the limit keeps under a client's 60 s request timeout. Time spent waiting for the session queue counts against that: a call whose wait plus its worst case would pass 60 s is refused with nothing sent. For a longer capture use start_profiler (up to 60 s) and stop_profiler."
    • addedInput schema / properties / seconds / exclusiveMinimum
      Added value: +0
    • addedInput schema / properties / seconds / maximum
      Added value: +30
    • addedInput schema / properties / targetFps
      Added value: +{
      +  "description": "Frame rate to hold the game to (default: 60). slowFrames counts frames whose frameMs exceeds 1000/targetFps, over the capture and per timeline interval. Under vsync every frame lasts the refresh interval: disable vsync, or set targetFps a few percent below the refresh rate.",
      +  "exclusiveMinimum": 0,
      +  "maximum": 1000,
      +  "type": "number"
      +}
    • addedInput schema / properties / timeline
      Added value: +{
      +  "description": "Also record the capture over time in `timeline.buckets`: per interval the fps, frameMs avg/max, process/physics/script ms, slowFrames, draw calls, render CPU/GPU ms (with visual) and the heaviest functions, server calls or render stages (`top`, named once in `timeline.items`) - where and when frames got slow (default: false). timelineMs, timelineTop, timelineBuckets and track turn it on by themselves; false beside any is rejected.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / timelineBuckets
      Added value: +{
      +  "description": "Most intervals the timeline reply holds, 4..60 (default: 20). A capture recorded in more is merged: adjacent intervals combine (counts and times add up, maxima stay) and `timeline.bucketMs` reports the width. Implies timeline.",
      +  "maximum": 60,
      +  "minimum": 4,
      +  "type": "integer"
      +}
    • addedInput schema / properties / timelineMs
      Added value: +{
      +  "description": "Timeline interval in milliseconds, 250..5000 (default: 500). Records at most about 60 intervals (60 s: 1000 ms) and the reply merges them down to timelineBuckets. Implies timeline.",
      +  "maximum": 5000,
      +  "minimum": 250,
      +  "type": "integer"
      +}
    • addedInput schema / properties / timelineTop
      Added value: +{
      +  "description": "Heaviest functions, server calls or render stages listed per timeline interval, 0..10 (default: 3). 0 leaves `top` empty. Implies timeline.",
      +  "maximum": 10,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • changedInput schema / properties / top / description
      Previous value: -"How many functions to return, 1..100 (default: 20)."New value: +"How many functions to return, 1..100 (default: 20). Also caps visual.areas when the capture recorded render stages."
    • addedInput schema / properties / top / maximum
      Added value: +100
    • addedInput schema / properties / top / minimum
      Added value: +1
    • changedInput schema / properties / top / type
      Previous value: -"number"New value: +"integer"
    • addedInput schema / properties / track
      Added value: +{
      +  "description": "Up to 4 NodePath:property values the game samples during the capture (every 250 ms, or half the interval when shorter), placed on the timeline by frame number, e.g. \"/root/Main/Player:global_position\" - where the player was when frames got slow. Implies timeline. Uses the bridge: drive the game between start_profiler and stop_profiler, not in parallel with profile_project. Collected only while the session that started the capture is current.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "maxItems": 4,
      +  "type": "array"
      +}
    • addedInput schema / properties / visual
      Added value: +{
      +  "description": "Also record the editor's Visual Profiler: CPU and GPU milliseconds per render stage (culling, shadows, opaque pass, canvas, ...) in `visual` (default: false). GPU times are null on GLES/web builds of the Compatibility renderer, which time no GPU work; `visual.gpuTimed` is false and a warning says so. A frame holds 256 render markers by default; a scene that needs more makes the engine log an error per lost marker, slowing the game, so the capture switches visual off and its warnings say how to raise the limit.",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / complete
      Added value: +{
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / fps
      Added value: +{
      +  "type": [
      +    "number",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / monitors
      Added value: +{
      +  "properties": {
      +    "bufferMemMiB": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "custom": {
      +      "items": {
      +        "properties": {
      +          "avg": {
      +            "type": "number"
      +          },
      +          "max": {
      +            "type": "number"
      +          },
      +          "min": {
      +            "type": "number"
      +          },
      +          "name": {
      +            "type": "string"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "drawCallsInFrame": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "nodes": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "objects": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "objectsInFrame": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "orphanNodes": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "physics2dActiveObjects": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "physics2dCollisionPairs": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "physics3dActiveObjects": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "physics3dCollisionPairs": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "pipelineCompilations": {
      +      "properties": {
      +        "duringCapture": {
      +          "type": [
      +            "number",
      +            "null"
      +          ]
      +        },
      +        "total": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "primitivesInFrame": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "resources": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "samples": {
      +      "type": "number"
      +    },
      +    "staticMemMiB": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "textureMemMiB": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "videoMemMiB": {
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    }
      +  },
      +  "type": [
      +    "object",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / projectPath
      Added value: +{
      +  "type": "string"
      +}
    • changedOutput schema / properties / rows / items / properties / percentOfFrame / type
      Previous value: -"number"New value: +[
      +  "number",
      +  "null"
      +]
    • addedOutput schema / properties / slowFrames
      Added value: +{
      +  "type": "number"
      +}
    • addedOutput schema / properties / targetFps
      Added value: +{
      +  "type": "number"
      +}
    • addedOutput schema / properties / timeline
      Added value: +{
      +  "properties": {
      +    "bucketMs": {
      +      "type": "number"
      +    },
      +    "buckets": {
      +      "items": {
      +        "properties": {
      +          "drawCalls": {
      +            "type": [
      +              "number",
      +              "null"
      +            ]
      +          },
      +          "fps": {
      +            "type": [
      +              "number",
      +              "null"
      +            ]
      +          },
      +          "frameMs": {
      +            "properties": {
      +              "avg": {
      +                "type": "number"
      +              },
      +              "max": {
      +                "type": "number"
      +              }
      +            },
      +            "type": [
      +              "object",
      +              "null"
      +            ]
      +          },
      +          "frames": {
      +            "type": "number"
      +          },
      +          "physicsMs": {
      +            "type": [
      +              "number",
      +              "null"
      +            ]
      +          },
      +          "processMs": {
      +            "type": [
      +              "number",
      +              "null"
      +            ]
      +          },
      +          "render": {
      +            "properties": {
      +              "cpuMs": {
      +                "type": "number"
      +              },
      +              "gpuMs": {
      +                "description": "Null when the renderer timed no GPU work (gpuTimed false).",
      +                "type": [
      +                  "number",
      +                  "null"
      +                ]
      +              }
      +            },
      +            "type": [
      +              "object",
      +              "null"
      +            ]
      +          },
      +          "scriptMs": {
      +            "type": [
      +              "number",
      +              "null"
      +            ]
      +          },
      +          "slowFrames": {
      +            "type": "number"
      +          },
      +          "t": {
      +            "type": "number"
      +          },
      +          "top": {
      +            "items": {
      +              "properties": {
      +                "item": {
      +                  "type": "integer"
      +                },
      +                "maxMs": {
      +                  "type": "number"
      +                },
      +                "ms": {
      +                  "type": "number"
      +                }
      +              },
      +              "type": "object"
      +            },
      +            "type": "array"
      +          },
      +          "track": {
      +            "description": "Tracked values that changed since the last interval with a sample, by spec: absent means unchanged, null means the value became null. The first sample lists every spec. null here means no sample landed in the interval.",
      +            "type": [
      +              "object",
      +              "null"
      +            ]
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "items": {
      +      "items": {
      +        "properties": {
      +          "kind": {
      +            "enum": [
      +              "script",
      +              "server",
      +              "render"
      +            ],
      +            "type": "string"
      +          },
      +          "name": {
      +            "type": "string"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "track": {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "trackError": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    }
      +  },
      +  "type": [
      +    "object",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / visual
      Added value: +{
      +  "properties": {
      +    "areas": {
      +      "items": {
      +        "properties": {
      +          "cpuMs": {
      +            "properties": {
      +              "avg": {
      +                "type": "number"
      +              },
      +              "max": {
      +                "type": "number"
      +              }
      +            },
      +            "type": "object"
      +          },
      +          "frames": {
      +            "type": "number"
      +          },
      +          "gpuMs": {
      +            "description": "Null when the renderer timed no GPU work (gpuTimed false).",
      +            "properties": {
      +              "avg": {
      +                "type": "number"
      +              },
      +              "max": {
      +                "type": "number"
      +              }
      +            },
      +            "type": [
      +              "object",
      +              "null"
      +            ]
      +          },
      +          "group": {
      +            "type": "boolean"
      +          },
      +          "name": {
      +            "type": "string"
      +          },
      +          "path": {
      +            "type": "string"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "areasReceived": {
      +      "type": "number"
      +    },
      +    "cpuMs": {
      +      "description": "Null when no render frame was folded (frames is 0).",
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "frames": {
      +      "type": "number"
      +    },
      +    "framesReceived": {
      +      "type": "number"
      +    },
      +    "gpuMs": {
      +      "description": "Null when no render frame was folded, or the renderer timed no GPU work.",
      +      "properties": {
      +        "avg": {
      +          "type": "number"
      +        },
      +        "max": {
      +          "type": "number"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "gpuTimed": {
      +      "type": "boolean"
      +    },
      +    "hardware": {
      +      "properties": {
      +        "cpu": {
      +          "type": "string"
      +        },
      +        "gpu": {
      +          "type": "string"
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "stoppedAt": {
      +      "type": [
      +        "number",
      +        "null"
      +      ]
      +    },
      +    "truncatedFrames": {
      +      "type": "number"
      +    },
      +    "worstFrame": {
      +      "properties": {
      +        "areas": {
      +          "items": {
      +            "properties": {
      +              "cpuMs": {
      +                "type": "number"
      +              },
      +              "gpuMs": {
      +                "description": "Null when the renderer timed no GPU work (gpuTimed false).",
      +                "type": [
      +                  "number",
      +                  "null"
      +                ]
      +              },
      +              "path": {
      +                "type": "string"
      +              }
      +            },
      +            "type": "object"
      +          },
      +          "type": "array"
      +        },
      +        "cpuMs": {
      +          "type": "number"
      +        },
      +        "frame": {
      +          "type": "number"
      +        },
      +        "gpuMs": {
      +          "description": "Null when the renderer timed no GPU work (gpuTimed false).",
      +          "type": [
      +            "number",
      +            "null"
      +          ]
      +        }
      +      },
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    }
      +  },
      +  "type": [
      +    "object",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / warnings
      Added value: +{
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / required
      Added value: +[
      +  "projectPath",
      +  "complete",
      +  "seconds",
      +  "frames",
      +  "fps",
      +  "targetFps",
      +  "slowFrames",
      +  "framesReceived",
      +  "firstFrame",
      +  "lastFrame",
      +  "frameGaps",
      +  "undecodablePackets",
      +  "captureLimit",
      +  "limitReached",
      +  "sort",
      +  "functionsReceived",
      +  "unresolvedFunctions",
      +  "frame",
      +  "servers",
      +  "rows",
      +  "worstFrame",
      +  "monitors",
      +  "visual",
      +  "timeline"
      +]
  2. Addedv3.4.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only say readOnly=false, destructive=false; the description goes far beyond them by disclosing that the call blocks for the whole window, that waits can reach ~58 s against a 60 s client timeout, that times are elapsed rather than CPU, and precisely which error conditions (profiling off, capture open, game exits mid-window) abort the call. That is behavioral context the annotations cannot carry.

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?

Front-loaded with the purpose, then prerequisites, blocking behavior, return shape, and errors in that order, with no filler sentences. It is dense to the point of being terse — several ideas are packed into semicolon chains — but every clause carries 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?

For an 11-parameter capture tool with no required params, the definition covers prerequisite state, duration and timeout limits, result ordering, and failure modes, and it defers return-value detail to the output schema that exists. Nothing an agent needs in order to invoke this correctly is absent.

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 3 is the baseline; the description earns a notch above by adding cross-parameter semantics not in the schema, notably that rows overlap so `totalMs` must not be summed, and that `seconds` has an effective ceiling imposed by client request timeouts rather than only by its documented max.

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?

Opens with a specific verb and resource ("Profile a window") and immediately enumerates what is measured: GDScript function costs, fps, monitors, plus what the `visual` and `timeline` switches add. It names its natural alternatives (start_profiler, run_project) so an agent can place it in the profiling workflow without opening another schema.

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?

States the prerequisite explicitly ("Requires run_project with profiling: true"), states the boundary condition for the other tool ("longer: start_profiler"), and gives a misuse warning ("never sum totalMs (rows overlap)"). It also warns that the bridge is exclusive with `track` captures, which is guidance an agent could not infer.

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