vtcode-utility-tool-specs 0.123.7

Passive JSON schemas for VT Code utility and file tool surfaces
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
//! Passive JSON schemas for utility, file, and scheduling tool surfaces.

#![recursion_limit = "256"]

use serde_json::{Value, json};

mod json_schema;
mod mcp_tool;
mod responses_api;

pub use json_schema::{AdditionalProperties, JsonSchema, parse_tool_input_schema};
pub use mcp_tool::{ParsedMcpTool, parse_mcp_tool};
pub use responses_api::{FreeformTool, FreeformToolFormat, ResponsesApiTool};

pub const SEMANTIC_ANCHOR_GUIDANCE: &str =
    "Prefer stable semantic @@ anchors such as function, class, method, or impl names.";
pub const APPLY_PATCH_ALIAS_DESCRIPTION: &str = "Alias for input";
pub const DEFAULT_APPLY_PATCH_INPUT_DESCRIPTION: &str = "Patch in VT Code format: *** Begin Patch, *** Update File: path, @@ hunk, -/+ lines, *** End Patch";

#[must_use]
pub fn with_semantic_anchor_guidance(base: &str) -> String {
    let trimmed = base.trim_end();
    if trimmed.contains(SEMANTIC_ANCHOR_GUIDANCE) {
        trimmed.to_string()
    } else if trimmed.ends_with('.') {
        format!("{trimmed} {SEMANTIC_ANCHOR_GUIDANCE}")
    } else {
        format!("{trimmed}. {SEMANTIC_ANCHOR_GUIDANCE}")
    }
}

#[must_use]
pub fn apply_patch_parameter_schema(input_description: &str) -> Value {
    json!({
        "type": "object",
        "properties": {
            "input": {
                "type": "string",
                "description": with_semantic_anchor_guidance(input_description)
            },
            "patch": {
                "type": "string",
                "description": APPLY_PATCH_ALIAS_DESCRIPTION
            }
        },
        "anyOf": [
            {"required": ["input"]},
            {"required": ["patch"]}
        ]
    })
}

#[must_use]
pub fn apply_patch_parameters() -> Value {
    apply_patch_parameter_schema(DEFAULT_APPLY_PATCH_INPUT_DESCRIPTION)
}

#[must_use]
pub fn cron_create_parameters() -> Value {
    json!({
        "type": "object",
        "required": ["prompt"],
        "properties": {
            "prompt": {"type": "string", "description": "Prompt to run when the task fires."},
            "name": {"type": "string", "description": "Optional short label for the task."},
            "cron": {"type": "string", "description": "Five-field cron expression for recurring tasks."},
            "delay_minutes": {"type": "integer", "description": "Fixed recurring interval in minutes."},
            "run_at": {
                "type": "string",
                "description": "One-shot fire time in RFC3339 or local datetime form. Use this instead of `cron` or `delay_minutes` for reminders."
            }
        }
    })
}

#[must_use]
pub fn cron_list_parameters() -> Value {
    json!({
        "type": "object",
        "properties": {}
    })
}

#[must_use]
pub fn cron_delete_parameters() -> Value {
    json!({
        "type": "object",
        "required": ["id"],
        "properties": {
            "id": {"type": "string", "description": "Session scheduled task id to delete."}
        }
    })
}

#[must_use]
pub fn unified_exec_parameters() -> Value {
    json!({
        "type": "object",
        "properties": {
            "command": {
                "description": "Command as a shell string or argv array.",
                "anyOf": [
                    {"type": "string"},
                    {
                        "type": "array",
                        "items": {"type": "string"}
                    }
                ]
            },
            "input": {"type": "string", "description": "stdin for write or continue."},
            "session_id": {"type": "string", "description": "Session id. Compact alias: `s`."},
            "spool_path": {"type": "string", "description": "Spool path for inspect."},
            "query": {"type": "string", "description": "Line filter for inspect or run output."},
            "head_lines": {"type": "integer", "description": "Head preview lines."},
            "tail_lines": {"type": "integer", "description": "Tail preview lines."},
            "max_matches": {"type": "integer", "description": "Max filtered matches.", "default": 200},
            "literal": {"type": "boolean", "description": "Treat query as literal text.", "default": false},
            "code": {"type": "string", "description": "Raw Python or JavaScript source for `action=code`. Send the source directly, not JSON or markdown fences."},
            "language": {
                "type": "string",
                "enum": ["python3", "javascript"],
                "description": "Language for `action=code`. Defaults to `python3`; set `javascript` to run Node-based code execution instead.",
                "default": "python3"
            },
            "action": {
                "type": "string",
                "enum": ["run", "write", "poll", "continue", "inspect", "list", "close", "code"],
                "description": "Optional; inferred from command/code/input/session_id/spool_path. Use `code` to run a fresh Python or JavaScript snippet through the local code executor."
            },
            "workdir": {"type": "string", "description": "Working directory."},
            "cwd": {"type": "string", "description": "Alias for workdir."},
            "tty": {"type": "boolean", "description": "Use PTY mode.", "default": false},
            "shell": {"type": "string", "description": "Shell binary."},
            "login": {"type": "boolean", "description": "Use a login shell.", "default": false},
            "sandbox_permissions": {
                "type": "string",
                "enum": ["use_default", "with_additional_permissions", "require_escalated"],
                "description": "Sandbox mode. Use `require_escalated` only when needed."
            },
            "additional_permissions": {
                "type": "object",
                "description": "Extra sandboxed filesystem access.",
                "properties": {
                    "fs_read": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "Extra readable paths."
                    },
                    "fs_write": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "Extra writable paths."
                    }
                },
                "additionalProperties": false
            },
            "justification": {"type": "string", "description": "Approval question for `require_escalated`."},
            "prefix_rule": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Optional persisted approval prefix for `command`."
            },
            "timeout_secs": {"type": "integer", "description": "Timeout seconds.", "default": 180},
            "yield_time_ms": {"type": "integer", "description": "Wait before returning output (ms).", "default": 1000},
            "confirm": {"type": "boolean", "description": "Confirm destructive ops.", "default": false},
            "max_output_tokens": {"type": "integer", "description": "Output token cap."},
            "track_files": {"type": "boolean", "description": "Track file changes.", "default": false}
        }
    })
}

#[must_use]
pub fn unified_file_parameters() -> Value {
    json!({
        "type": "object",
        "properties": {
            "action": {
                "type": "string",
                "enum": ["read", "write", "edit", "patch", "delete", "move", "copy"],
                "description": "Optional; inferred from old_str/patch/content/destination/path."
            },
            "path": {"type": "string", "description": "File path. Accepts file_path/filepath/target_path/file/p."},
            "content": {"type": "string", "description": "Content for write."},
            "old_str": {"type": "string", "description": "Exact text to replace for edit."},
            "new_str": {"type": "string", "description": "Replacement text for edit."},
            "patch": {"type": "string", "description": "Patch text in `*** Update File:` format, not unified diff."},
            "destination": {"type": "string", "description": "Destination for move or copy."},
            "start_line": {"type": "integer", "description": "Read start line (1-indexed)."},
            "end_line": {"type": "integer", "description": "Read end line (inclusive)."},
            "offset": {"type": "integer", "description": "Read start line. Compact alias: `o`."},
            "limit": {"type": "integer", "description": "Read line count. Compact alias: `l`."},
            "mode": {"type": "string", "description": "Read mode or write mode.", "default": "slice"},
            "condense": {"type": "boolean", "description": "Condense long output.", "default": true},
            "indentation": {
                "description": "Indentation config. `true` uses defaults.",
                "anyOf": [
                    {"type": "boolean"},
                    {
                        "type": "object",
                        "properties": {
                            "anchor_line": {"type": "integer", "description": "Anchor line; defaults to offset."},
                            "max_levels": {"type": "integer", "description": "Indent depth cap; 0 means unlimited."},
                            "include_siblings": {"type": "boolean", "description": "Include sibling blocks."},
                            "include_header": {"type": "boolean", "description": "Include header lines."},
                            "max_lines": {"type": "integer", "description": "Optional line cap."}
                        },
                        "additionalProperties": false
                    }
                ]
            }
        }
    })
}

#[must_use]
pub fn read_file_parameters() -> Value {
    json!({
        "type": "object",
        "properties": {
            "path": {"type": "string", "description": "File path. Accepts file_path/filepath/target_path/file/p."},
            "offset": {"type": "integer", "description": "1-indexed line offset. Compact alias: `o`.", "minimum": 1},
            "limit": {"type": "integer", "description": "Max lines for this chunk. Compact alias: `l`.", "minimum": 1},
            "mode": {"type": "string", "enum": ["slice", "indentation"], "description": "Read mode.", "default": "slice"},
            "indentation": {
                "description": "Indentation-aware block selection.",
                "anyOf": [
                    {"type": "boolean"},
                    {
                        "type": "object",
                        "properties": {
                            "anchor_line": {"type": "integer", "description": "Anchor line; defaults to offset."},
                            "max_levels": {"type": "integer", "description": "Indent depth cap; 0 means unlimited."},
                            "include_siblings": {"type": "boolean", "description": "Include sibling blocks."},
                            "include_header": {"type": "boolean", "description": "Include header lines."},
                            "max_lines": {"type": "integer", "description": "Optional line cap."}
                        },
                        "additionalProperties": false
                    }
                ]
            },
            "offset_lines": {"type": "integer", "description": "Legacy alias for line offset.", "minimum": 1},
            "page_size_lines": {"type": "integer", "description": "Legacy alias for line chunk size.", "minimum": 1},
            "offset_bytes": {"type": "integer", "description": "Byte offset for binary or byte-paged reads.", "minimum": 0},
            "page_size_bytes": {"type": "integer", "description": "Byte page size for binary or byte-paged reads.", "minimum": 1},
            "max_bytes": {"type": "integer", "description": "Maximum bytes to return.", "minimum": 1},
            "max_lines": {"type": "integer", "description": "Maximum lines to return in legacy mode.", "minimum": 1},
            "chunk_lines": {"type": "integer", "description": "Legacy alias for chunk size in lines.", "minimum": 1},
            "max_tokens": {"type": "integer", "description": "Optional token budget for large reads.", "minimum": 1},
            "condense": {"type": "boolean", "description": "Condense long outputs to head/tail.", "default": true}
        }
    })
}

#[must_use]
pub fn unified_search_parameters() -> Value {
    json!({
        "type": "object",
        "properties": {
            "action": {
                "type": "string",
                "enum": ["grep", "list", "structural", "tools", "errors", "agent", "web", "skill"],
                "description": "Action to perform. Default to `structural` for code or syntax-aware search, including read-only ast-grep `run` query, project scan, and project test workflows; use `grep` for raw text and `list` for file discovery. Refine and retry `grep` or `structural` here before switching tools."
            },
            "workflow": {
                "type": "string",
                "enum": ["query", "scan", "test", "rewrite", "new", "apply"],
                "description": "Structural workflow. `query` is the default parseable-pattern search and maps to read-only ast-grep `run`; `scan` maps to read-only ast-grep `scan` from config; `test` runs ast-grep rule tests; `rewrite` previews pattern-to-pattern replacements without applying them, supporting both simple string fixes via `rewrite` and advanced FixConfig rewrites via `fix_config` with `expand_start`/`expand_end` for range expansion; `apply` writes rewrites to disk (same parameters as `rewrite`); `new` scaffolds ast-grep projects, rules, tests, and utilities via `new_subcommand` and `new_name`.",
                "default": "query"
            },
            "pattern": {"type": "string", "description": "For `grep` or `errors`, regex or literal text. For `list`, a glob filter for returned paths or names; nested globs such as `**/*.rs` promote `list` to recursive discovery. For `structural` `workflow=\"query\"`, valid parseable code for the selected language using ast-grep pattern syntax, not a raw code fragment; `$VAR` matches one named node, `$$$ARGS` matches zero or more nodes, `$$VAR` includes unnamed nodes, and `$_` suppresses capture. If a fragment fails, retry `action='structural'` with a larger parseable pattern such as a full function signature. At least one of `pattern` or `kind` is required for `workflow=\"query\"`. For `structural` `workflow=\"rewrite\"`, the pattern to match for replacement; required."},
            "kind": {"type": "string", "description": "Ast-grep tree-sitter node kind for structural `workflow=\"query\"`. Matches nodes by their AST kind name directly, e.g. `function_item`, `call_expression`, `if_statement`. Supports ESQuery-style compound selectors: `A > B` (direct child), `A B` (descendant), `A + B` (immediate sibling), `A ~ B` (general sibling), and `A, B` (either). Also supports pseudo-selectors: `:has(selector)` or `:has(> selector)` for descendants/direct children, `:not(selector)` for exclusion, `:is(selector, ...)` for alternatives, `:nth-child(An+B)` or `:nth-child(An+B of selector)` for positional matching, and `:nth-last-child(position)` for reverse positional matching. Can be used alone or combined with `pattern`; when both are present, `kind` filters the pattern matches by node kind. At least one of `pattern` or `kind` is required for `workflow=\"query\"`."},
            "path": {"type": "string", "description": "Directory or file path to search in. Used by `grep`, `list`, and structural `workflow=\"query\"|\"scan\"`. Public structural calls take one root per request even though raw ast-grep `run` can accept multiple paths.", "default": "."},
            "config_path": {"type": "string", "description": "Ast-grep config path for structural `workflow=\"scan\"` or `workflow=\"test\"`. Defaults to workspace `sgconfig.yml`."},
            "filter": {"type": "string", "description": "Ast-grep rule or test filter for structural `workflow=\"scan\"` or `workflow=\"test\"`. On `scan`, this maps to `--filter` over rule ids from config."},
            "lang": {"type": "string", "description": "Language for structural `workflow=\"query\"` or `workflow=\"rewrite\"`. Set it whenever the code language is known; required for debug_query and recommended for rewrite."},
            "selector": {"type": "string", "description": "Ast-grep selector for structural `workflow=\"query\"` when the real match is a subnode inside the parseable pattern. Supports ESQuery-style pseudo-selectors: `:has(selector)`, `:not(selector)`, `:is(selector, ...)`, `:nth-child(An+B)`, and `:nth-child(An+B of selector)`. In YAML rules and `--kind` mode, `kind` also accepts compound selectors: `A > B` (direct child), `A B` (descendant), `A + B` (immediate sibling), `A ~ B` (general sibling), and `A, B` (either)."},
            "strictness": {
                "type": "string",
                "enum": ["cst", "smart", "ast", "relaxed", "signature", "template"],
                "description": "Pattern strictness for structural `workflow=\"query\"`."
            },
            "debug_query": {
                "type": "string",
                "enum": ["pattern", "ast", "cst", "sexp"],
                "description": "Print the structural query AST instead of matches for `workflow=\"query\"`. Requires lang."
            },
            "globs": {
                "description": "Optional include/exclude globs for structural `workflow=\"query\"` or `workflow=\"scan\"`. Maps to repeated ast-grep `--globs` flags.",
                "anyOf": [
                    {"type": "string"},
                    {"type": "array", "items": {"type": "string"}}
                ]
            },
            "skip_snapshot_tests": {"type": "boolean", "description": "Skip ast-grep snapshot tests for structural `workflow=\"test\"`.", "default": false},
            "rewrite": {"type": "string", "description": "Replacement string for structural `workflow=\"rewrite\"`. Meta variables from `pattern` can be referenced (e.g. `$VAR`, `$$$ARGS`). For simple pattern-to-pattern rewrites. Either `rewrite` or `fix_config` is required for `workflow=\"rewrite\"`."},
            "fix_config": {
                "type": "object",
                "description": "Advanced fix configuration for structural `workflow=\"rewrite\"`. Use when replacing only the matched node is not enough, especially for deleting list items or key-value pairs that also need a surrounding comma removed. Either `rewrite` or `fix_config` is required for `workflow=\"rewrite\"`.",
                "properties": {
                    "template": {"type": "string", "description": "Replacement template string. Meta variables from `pattern` can be referenced."},
                    "expand_start": {
                        "type": "object",
                        "description": "Rule to expand the fix range start backwards until the rule is no longer met. At least one of `regex`, `kind`, or `pattern` is required.",
                        "properties": {
                            "regex": {"type": "string", "description": "Regex pattern to match for expansion."},
                            "kind": {"type": "string", "description": "Tree-sitter node kind to match for expansion."},
                            "pattern": {"type": "string", "description": "Ast-grep pattern to match for expansion."},
                            "stop_by": {"description": "Controls where expansion stops. String value like `\"line\"` or `\"end\"`, or a rule object."}
                        }
                    },
                    "expand_end": {
                        "type": "object",
                        "description": "Rule to expand the fix range end forwards until the rule is no longer met. At least one of `regex`, `kind`, or `pattern` is required.",
                        "properties": {
                            "regex": {"type": "string", "description": "Regex pattern to match for expansion."},
                            "kind": {"type": "string", "description": "Tree-sitter node kind to match for expansion."},
                            "pattern": {"type": "string", "description": "Ast-grep pattern to match for expansion."},
                            "stop_by": {"description": "Controls where expansion stops. String value like `\"line\"` or `\"end\"`, or a rule object."}
                        }
                    }
                },
                "required": ["template"]
            },
            "new_subcommand": {"type": "string", "enum": ["project", "rule", "test", "util"], "description": "Subcommand for structural `workflow=\"new\"`. `project` scaffolds sgconfig.yml and directories; `rule` creates a new rule YAML; `test` creates a new test YAML; `util` creates a new utility rule."},
            "new_name": {"type": "string", "description": "Name for the new rule, test, or utility. Required for `new` subcommands `rule`, `test`, and `util`."},
            "keyword": {"type": "string", "description": "Keyword for 'tools' search."},
            "url": {"type": "string", "format": "uri", "description": "The URL to fetch content from (for 'web' action)."},
            "prompt": {"type": "string", "description": "The prompt to run on the fetched content (for 'web' action)."},
            "name": {"type": "string", "description": "Skill name to load (for 'skill' action)."},
            "detail_level": {
                "type": "string",
                "enum": ["name-only", "name-and-description", "full"],
                "description": "Detail level for 'tools' action.",
                "default": "name-and-description"
            },
            "mode": {
                "type": "string",
                "description": "Mode for 'list' (list|recursive|tree|etc) or 'agent' (debug|analyze|full) action.",
                "default": "list"
            },
            "max_results": {"type": "integer", "description": "Max results to return.", "default": 100},
            "case_sensitive": {"type": "boolean", "description": "Case-sensitive search.", "default": false},
            "context_lines": {"type": "integer", "description": "Context lines for `grep` or structural `workflow=\"query\"|\"scan\"` results. Structural maps this to ast-grep `--context`; raw `--before` and `--after` are not exposed separately.", "default": 0},
            "severities": {
                "type": "array",
                "items": {"type": "string", "enum": ["error", "warning", "info", "hint"]},
                "description": "Post-run severity filter for structural `workflow=\"scan\"`. When present, only findings matching one of the listed severities are returned. Does not override rule severities at the CLI level."
            },
            "no_ignore": {
                "type": "array",
                "items": {"type": "string", "enum": ["hidden", "dot", "exclude", "global", "parent", "vcs"]},
                "description": "Control which ignore files ast-grep respects for structural workflows. `hidden` searches hidden files/dirs; `dot` skips .ignore files; `exclude` skips manually configured excludes; `global` skips global ignore files; `parent` skips parent directory ignores; `vcs` skips VCS ignore files."
            },
            "follow": {"type": "boolean", "description": "Follow symbolic links while traversing directories for structural workflows.", "default": false},
            "threads": {"type": "integer", "description": "Number of threads for ast-grep scan parallelism. 0 means auto. Only for `workflow=\"scan\"`.", "minimum": 0, "maximum": 256, "default": 0},
            "format": {"type": "string", "enum": ["github", "sarif"], "description": "Output format for CI pipelines for structural `workflow=\"scan\"`. When set, returns raw formatted output instead of normalized JSON."},
            "report_style": {"type": "string", "enum": ["rich", "medium", "short"], "description": "Diagnostic report style for structural `workflow=\"scan\"`. Controls verbosity of diagnostic output."},
            "before_lines": {"type": "integer", "description": "Context lines before each match for structural workflows. Mutually exclusive with `context_lines`.", "minimum": 0, "maximum": 20},
            "after_lines": {"type": "integer", "description": "Context lines after each match for structural workflows. Mutually exclusive with `context_lines`.", "minimum": 0, "maximum": 20},
            "builtin_rules": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Built-in ast-grep rules to activate for `workflow=\"scan\"`. Valid values: `unused-suppression` (reports stale ignore directives), `no-suppress-all` (reports suppress-all comments). Use `\"rule:severity\"` format to set severity (e.g. `\"unused-suppression:error\"`). Default severity is hint."
            },
            "scope": {"type": "string", "description": "Scope for 'errors' action (archive|all).", "default": "archive"},
            "max_bytes": {"type": "integer", "description": "Maximum bytes to fetch for 'web' action.", "default": 500000},
            "timeout_secs": {"type": "integer", "description": "Timeout in seconds.", "default": 30}
        }
    })
}

#[must_use]
pub fn list_files_parameters() -> Value {
    json!({
        "type": "object",
        "properties": {
            "path": {"type": "string", "description": "Directory or file path to inspect.", "default": "."},
            "mode": {
                "type": "string",
                "enum": ["list", "recursive", "tree", "find_name", "find_content", "largest", "file", "files"],
                "description": "Listing mode. Use page/per_page to continue paginated results.",
                "default": "list"
            },
            "pattern": {"type": "string", "description": "Optional glob-style path filter."},
            "name_pattern": {"type": "string", "description": "Optional name filter for list/find_name modes."},
            "content_pattern": {"type": "string", "description": "Content query for find_content mode."},
            "page": {"type": "integer", "description": "1-indexed results page.", "minimum": 1},
            "per_page": {"type": "integer", "description": "Items per page.", "minimum": 1},
            "max_results": {"type": "integer", "description": "Maximum total results to consider before pagination.", "minimum": 1},
            "include_hidden": {"type": "boolean", "description": "Include dotfiles and hidden entries.", "default": false},
            "response_format": {"type": "string", "enum": ["concise", "detailed"], "description": "Verbosity of the listing output.", "default": "concise"},
            "case_sensitive": {"type": "boolean", "description": "Case-sensitive name matching.", "default": false}
        }
    })
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;

    #[test]
    fn apply_patch_parameter_schema_keeps_alias_and_guidance_consistent() {
        let schema = apply_patch_parameter_schema("Patch in VT Code format");

        assert_eq!(
            schema["properties"]["patch"]["description"],
            APPLY_PATCH_ALIAS_DESCRIPTION
        );
        let input_description = schema["properties"]["input"]["description"]
            .as_str()
            .expect("input description");
        assert!(input_description.contains(SEMANTIC_ANCHOR_GUIDANCE));
    }

    #[test]
    fn unified_exec_schema_accepts_string_or_array_commands() {
        let params = unified_exec_parameters();
        let command = &params["properties"]["command"];
        let variants = command["anyOf"].as_array().expect("command anyOf");

        assert_eq!(variants.len(), 2);
        assert_eq!(variants[0]["type"], "string");
        assert_eq!(variants[1]["type"], "array");
        assert_eq!(variants[1]["items"]["type"], "string");
        assert_eq!(params["properties"]["tty"]["type"], "boolean");
        assert_eq!(params["properties"]["tty"]["default"], false);
        assert!(
            params["properties"]["code"]["description"]
                .as_str()
                .expect("code description")
                .contains("Raw Python or JavaScript source")
        );
        assert!(
            params["properties"]["language"]["description"]
                .as_str()
                .expect("language description")
                .contains("set `javascript`")
        );
    }

    #[test]
    fn unified_search_schema_advertises_structural_and_hides_intelligence() {
        let params = unified_search_parameters();
        let actions = params["properties"]["action"]["enum"]
            .as_array()
            .expect("action enum");

        assert!(actions.iter().any(|value| value == "structural"));
        assert!(!actions.iter().any(|value| value == "intelligence"));
        assert!(
            params["properties"]["debug_query"]["enum"]
                .as_array()
                .expect("debug_query enum")
                .iter()
                .any(|value| value == "ast")
        );
        assert!(
            params["properties"]["action"]["description"]
                .as_str()
                .expect("action description")
                .contains("Default to `structural`")
        );
        assert!(
            params["properties"]["pattern"]["description"]
                .as_str()
                .expect("pattern description")
                .contains("valid parseable code")
        );
        assert!(
            params["properties"]["pattern"]["description"]
                .as_str()
                .expect("pattern description")
                .contains("$$$ARGS")
        );
        assert!(
            params["properties"]["pattern"]["description"]
                .as_str()
                .expect("pattern description")
                .contains("glob filter")
        );
        assert!(
            params["properties"]["action"]["description"]
                .as_str()
                .expect("action description")
                .contains("Refine and retry `grep` or `structural`")
        );
        assert_eq!(params["properties"]["workflow"]["enum"][1], "scan");
        assert_eq!(params["properties"]["workflow"]["enum"][2], "test");
        assert!(
            params["properties"]["config_path"]["description"]
                .as_str()
                .expect("config path description")
                .contains("Defaults to workspace `sgconfig.yml`")
        );
        assert!(
            params["properties"]["skip_snapshot_tests"]["description"]
                .as_str()
                .expect("skip snapshot description")
                .contains("workflow=\"test\"")
        );
    }

    #[test]
    fn legacy_browse_tool_schemas_expose_chunking_and_pagination_fields() {
        let read_params = read_file_parameters();
        assert!(read_params["properties"]["offset"].is_object());
        assert!(read_params["properties"]["limit"].is_object());
        assert!(read_params["properties"]["page_size_lines"].is_object());

        let list_params = list_files_parameters();
        assert!(list_params["properties"]["page"].is_object());
        assert!(list_params["properties"]["per_page"].is_object());
        assert!(
            list_params["properties"]["mode"]["enum"]
                .as_array()
                .expect("mode enum")
                .iter()
                .any(|value| value == "recursive")
        );
    }

    #[test]
    fn semantic_anchor_guidance_is_appended_once() {
        let base = "Patch in VT Code format.";
        let with_guidance = with_semantic_anchor_guidance(base);

        assert!(with_guidance.contains(SEMANTIC_ANCHOR_GUIDANCE));
        assert_eq!(with_semantic_anchor_guidance(&with_guidance), with_guidance);
    }

    #[test]
    fn default_apply_patch_parameters_keep_expected_alias_shape() {
        let schema = apply_patch_parameters();

        assert_eq!(
            schema["anyOf"],
            json!([
                {"required": ["input"]},
                {"required": ["patch"]}
            ])
        );
    }
}