# create_spec

Generate a functional-requirements spec (.3tg.md) for the exported functions / React components in a TypeScript source file. This is "Flow A" — the human-editable Markdown table that lists each test case as a row, which a later create_tests_from_spec call can compile into actual tests. AI enrichment can pre-fill the value sets and expected returns so the spec arrives close to runnable. IMPORTANT — never hand-author a .3tg.md yourself. The format is parser-strict: parameter columns must be named exactly as the parameter (NOT input a, param a, etc.), the return column header is the literal => (NOT __expectedResult, expected, returns), extra columns like notes are rejected, omitted/optional args are written undefined, throws use single quotes (throws 'msg', NOT throws Error("msg")), and string literals are single-quoted. Always call this tool to emit the scaffold; the user can then edit rows. The returned .3tg.md is reported under the project's .3tg/ mirror (e.g. source src/foo/bar.ts → spec .3tg/src/foo/bar.3tg.md). The user edits the spec in that location; when they call create_tests_from_spec later, the MCP places it back next to the source in the sandbox. Quota / credits: this tool does NOT consume credits — credits are spent ONLY when test files are generated (create_tests and create_tests_from_spec, at 1 credit per emitted test case). Spec generation is free; iterate on the scaffold as often as needed. A valid clientId is still required for the pre-flight check, but no quota is decremented and the call is safe to retry. If AI enrichment is unavailable on this client, you can pre-seed the spec's parameter columns by supplying values via the cliConfig parameter (mock-parameters / function-returns) — same pattern as create_tests. Do NOT autonomously write .3tg/config.3tg.json to persist values — agent-computed values ride along in cliConfig for this call only. (Explicit user requests to edit the file are fine — handle those normally.) See the cliConfig parameter description for the full shape. CRITICAL POST-CALL ACTION — write returned files to disk: The MCP server does NOT touch the user's filesystem. It returns the generated file CONTENTS in the response's files array. After this tool returns, you MUST iterate over files and write each entry's content verbatim to its path using your native file-write capability (e.g. Write / edit_file / create_file — whatever your client exposes). Create parent directories as needed. Returned paths are project-root-relative and already translated to the .3tg/ mirror convention where applicable (e.g. specs land under .3tg/<source-path>.3tg.md; tests / mocks travel through unchanged). Write each path verbatim. Do NOT claim "Generated test file: <path>" unless you have actually written the file. The user will assume the MCP wrote it and waste time looking for a non-existent file. If you can't write for some reason (permission denied, no write capability in this client), return the contents inline in your message so the user can copy-paste them. Never report success silently when the write didn't happen.

Agent View of the PolicyLayer registry record for `create_spec`. HTML page: https://policylayer.com/tools/dev-3tg-mcp/create-spec

## Facts

- Tool: `create_spec`
- Server: 3TG Test Generation (`https://mcp.3tg.dev/mcp`) — https://policylayer.com/tools/dev-3tg-mcp.md
- Homepage: https://github.com/https://mcp.3tg.dev/mcp
- Risk category: Write (Medium risk)
- Registry record: grade D, identity unverified
- Server auth posture: open
- Server rate-limited: no
- Parameters: 6 (3 required)
- Recommended policy verdict: Rate-limited

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `clientId` | string | yes | The 3tg.dev client ID. |
| `fileName` | string | yes | Path of the source file relative to the user's project root (e.g. "src/foo/bar.ts"). The spec is derived as the same path with `.ts` / `.tsx` replaced by `.3tg. |
| `settings` | object | no | Subset of .3tg/settings.json relevant to this tool. |
| `cliConfig` | object | no | Optional per-request 3TG CLI config. The agent assembles this from TWO disk locations and merges them (per-source wins on conflict) before forwarding the merged |
| `moduleType` | string | no | Optional Node module type of the consumer project — the value of the `type` field in the project root's `package.json`. The agent reads that one field (only) an |
| `sourceCode` | string | yes | Full UTF-8 contents of the source file. |

Parameters from the server's own tool schema.

## Example call (MCP tools/call, JSON-RPC 2.0)

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_spec",
    "arguments": {
      "clientId": "<clientId>",
      "fileName": "<fileName>",
      "sourceCode": "<sourceCode>"
    }
  }
}
```

## Why create_spec is rated Medium

This is a Write operation: it creates a new spec file artifact that documents test requirements. While the output is structured and machine-consumed later, the operation is reversible (the file can be edited, deleted, or regenerated), and it does not execute code, delete data, or move money. The generated spec is configuration/metadata, not executable operations.

From the tool's own definition: "The tool creates or generates a functional-requirements spec file (`.3tg.md`) from TypeScript source. The description states it generates output that is 'human-editable' and can be 'close to runnable,' indicating reversible creation of structured…"

Risk signals: Accepts file system path (fileName) · High parameter count (11 properties) · Admin/system-level operation

## Use case

AI agents use create_spec to create or update resources in 3TG Test Generation, usually the action step of a workflow, after the agent has gathered context. Every call changes real data in your 3TG Test Generation environment.

## Recommended policy (PolicyLayer)

Verdict: **Rate-limited**. Enforced by the PolicyLayer MCP gateway (https://policylayer.com/mcp-gateway) before a call reaches 3TG Test Generation:

```json
{
  "version": "1",
  "default": "deny",
  "tools": {
    "create_spec": {
      "limits": [
        {
          "counter": "create_spec_rate",
          "window": "minute",
          "max": 30,
          "scope": "grant"
        }
      ]
    }
  }
}
```

## Other tools on 3TG Test Generation (9)

- `get_client_info` — Read — https://policylayer.com/tools/dev-3tg-mcp/get-client-info.md
- `help` — Read — https://policylayer.com/tools/dev-3tg-mcp/help.md
- `validate_config` — Read — https://policylayer.com/tools/dev-3tg-mcp/validate-config.md
- `validate_spec` — Read — https://policylayer.com/tools/dev-3tg-mcp/validate-spec.md
- `create_agent_instructions` — Write — https://policylayer.com/tools/dev-3tg-mcp/create-agent-instructions.md
- `create_mock_for_function` — Write — https://policylayer.com/tools/dev-3tg-mcp/create-mock-for-function.md
- `create_spec_for_function` — Write — https://policylayer.com/tools/dev-3tg-mcp/create-spec-for-function.md
- `create_tests` — Write — https://policylayer.com/tools/dev-3tg-mcp/create-tests.md
- `create_tests_from_spec` — Write — https://policylayer.com/tools/dev-3tg-mcp/create-tests-from-spec.md

## For agents

This record is a snapshot. Live verdicts and the full registry:

- Check every server in your MCP config at once: `npx -y policylayer stack`
- Vet a server before you add it: install the mcp-precheck skill — `npx skills add https://policylayer.com` (skill text: https://policylayer.com/skill.md)
- Query the registry over MCP: endpoint `https://api.policylayer.com/mcp` — tools `check_mcp_server`, `check_mcp_stack`, `check_tool`, `search_registry`, `get_change_events`

---

Source: the PolicyLayer MCP registry — one continuously verified record per MCP server. Full record: https://policylayer.com/registry?q=dev-3tg-mcp · API: https://policylayer.com/registry/api · Policy library: https://policylayer.com/policies/dev-3tg-mcp