Skip to main content
Glama

get_ctlsurf_instructions

Initialize a project with ctlsurf or get ctlsurf integration instructions.

Use this when the user says "initialize project with ctlsurf" or "set up ctlsurf for this project".

Returns instructions to add to your project memory/config file (CLAUDE.md, AGENTS.md, .cursorrules, etc.):

  • ctlsurf as source of truth

  • Checking pending tasks on session start

  • Documenting assumptions, shortcuts, decisions

  • Task workflow (claim, progress, complete, follow-up)

  • Block types guide (text, checklist, table, tree, react_flow, ctlsurf_task, datastore, state, log)

  • When to update documentation

Usage:

  1. Detect the git remote URL: run git remote get-url origin

  2. Detect the hostname: run hostname

  3. Call this tool with root_path, repo_url, and hostname

  4. If the result has needs_project_choice=true, this checkout (e.g. a fresh clone on a new machine, or a teammate's clone) matches existing projects for the same repo. Show the user the candidates and ASK which project to link it to, then call again with folder_id=; if they want a separate project, call again with create_new=true.

  5. Add the returned 'instructions' to your project memory/config file

A project can live on many machines: each checkout (machine + path) is added to the project's machine list, so several people on several machines share one project.

Examples:

  • get_ctlsurf_instructions(root_path="/path/to/project", repo_url="https://github.com/user/repo", hostname="macbook-pro")

  • get_ctlsurf_instructions(root_path="/path/to/project", repo_url="...", hostname="...", folder_id="")

  • get_ctlsurf_instructions(root_path="/path/to/project", format="text")

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "root_path": "<root_path>"
    },
    "name": "get_ctlsurf_instructions"
  }
}

Input Schema

NameRequiredDescriptionDefault
formatNoOutput format: 'markdown' for CLAUDE.md/Copilot, 'text' for .cursorrules/.windsurfrules (default: markdown)
hostnameNoMachine hostname. Auto-detected by the agent via `hostname` or `uname -n` command. Added to the project's machine list.
repo_urlNoGit repository URL (preferred). Detect with: git remote get-url origin
folder_idNoLink this checkout to this existing project (an id from a previous needs_project_choice result, chosen by the user).
root_pathYesProject root path
create_newNoThe user wants a separate project for this checkout even though projects for the same repo exist.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / properties / create_new
      Added value: +{
      +  "description": "The user wants a separate project for this checkout even though projects for the same repo exist.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / folder_id
      Added value: +{
      +  "description": "Link this checkout to this existing project (an id from a previous needs_project_choice result, chosen by the user).",
      +  "type": "string"
      +}
    • changedInput schema / properties / hostname / description
      Previous value: -"Machine hostname. Auto-detected by the agent via `hostname` or `uname -n` command. Used to track which computer a project lives on."New value: +"Machine hostname. Auto-detected by the agent via `hostname` or `uname -n` command. Added to the project's machine list."
  2. First observed

TDQS

A4.6/5.0
Behavior4/5

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

With no annotations, the description carries the burden well: it discloses the returned payload ('instructions'), the needs_project_choice branch, and the side effect that each checkout is appended to the project's machine list, which is a mutation an agent should know about. It stops short of noting auth requirements, whether repeated calls are idempotent, or how large the returned instruction text is.

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 front-loaded with purpose, then trigger phrases, then a numbered usage sequence, then worked examples. The three examples largely restate the steps above, and the bulleted content list is thorough to the point of padding, but nothing is confusing or buried.

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?

There is no output schema, and the description compensates by describing the shape of the result ('instructions', needs_project_choice, candidate projects) and the exact place the output goes (CLAUDE.md, AGENTS.md, .cursorrules). For a six-parameter setup tool this is complete enough to call 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?

Schema coverage is already 100%, so baseline is 3, but the description adds real meaning: it explains how to derive repo_url (git remote get-url origin) and hostname (hostname), and it defines the conditional semantics of folder_id and create_new within the needs_project_choice flow. It also restates the format trade-off (text for .cursorrules/.windsurfrules) already covered by the enum description.

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 names a specific verb and resource ('Initialize a project with ctlsurf or get ctlsurf integration instructions') and enumerates exactly what the returned instructions cover, so an agent can distinguish it from siblings like get_pending_agent_tasks or find_page_by_root_path without opening a 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?

It supplies explicit trigger utterances, a numbered procedure (detect remote, detect hostname, call, handle needs_project_choice, write instructions to config), and states the alternative paths: call again with folder_id when linking to an existing project, or create_new=true for a separate project.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources