[WIP] Add schema descriptions for tool restrictions

[Copilot]

Implementation Complete: Tool Restrictions Documented

Changes Made

• Investigate tool availability in both schemas
• Analyze codebase for technical restrictions
• Determine if restriction is intentional or oversight
• Add comprehensive description field to tools property in included_file_schema.json
• Document which tools are available and why
• Explain the rationale for tool restrictions
• Test schema validates correctly
• Verify no breaking changes
• Clean up test artifacts

Implementation Summary

File Modified: pkg/parser/schemas/included_file_schema.json

Added comprehensive documentation to the tools property description field explaining:

1. Available Tools in Included Files (4):

   • bash - Shell command execution
   • cache-memory - Persistent memory storage
   • github - GitHub API operations
   • repo-memory - Git-based persistent storage

2. Tools Restricted to Main Workflows (9):

   • Full-featured tools: playwright, web-fetch, web-search, edit, agentic-workflows, serena
   • Engine-specific configs: timeout, startup-timeout, safety-prompt

3. Design Rationale:

   • Included files are for shared configurations and reusable tool settings
   • Main workflows handle full-featured tools and workflow-specific behavior
   • This separation maintains clear boundaries and prevents complexity

Validation

✅ Build: Successfully rebuilt with schema changes embedded
✅ Tests: All unit tests pass (make test-unit)
✅ Schema Validation: Compiled test workflow with included file successfully
✅ No Breaking Changes: Existing functionality preserved

Technical Decision

Selected Option 1: Document the restriction rather than expand tool support

Rationale:

• Restriction is intentional design pattern
• Included files serve as shared configuration containers
• Main workflows own full tool behavior and orchestration
• Lower risk approach with clear intent
• No potential for edge cases from complex tool merging

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[plan] Document tool restrictions in included_file_schema.json</issue_title>
<issue_description>## Objective

Add schema descriptions explaining why only 4 of 13 tools are available in included files, or expand tool support if the restriction is unintentional.

Context

Priority: MODERATE
Category: Feature Parity / Documentation

Currently:

• Main Schema: 13 tool configuration properties
• Included Schema: 4 tool configuration properties (bash, cache-memory, github, repo-memory)

Missing Tools: agentic-workflows, edit, playwright, safety-prompt, serena, startup-timeout, timeout, web-fetch, web-search

It's unclear if this restriction is intentional design or an oversight, and there's no documentation explaining the limitation.

Approach

Option 1: If restriction is intentional

1. Add description field to the tools property in included_file_schema.json
2. Document why included files have restricted tool access
3. Explain which tools are available and why others are excluded

Option 2: If restriction is unintentional

1. Add missing 9 tool properties to included_file_schema.json
2. Copy tool definitions from main_workflow_schema.json
3. Test that all tools work correctly in included files

Decision Criteria:

• Review codebase to determine if there's a technical reason for the restriction
• Check if included files have access to tool implementations
• Consult with maintainers if needed

Files to Modify

• Update: pkg/parser/schemas/included_file_schema.json
  • Add description to tools property (Option 1)
  • OR add 9 missing tool properties (Option 2)

Acceptance Criteria

• Tool restrictions are clearly documented in schema
• OR all 13 tools are available in included files
• Decision rationale is captured in commit message
• Schema validates correctly
• No breaking changes to existing workflows

Research Questions

Before implementing, investigate:

1. Are there technical limitations preventing tool use in included files?
2. Is this a security boundary (included files as untrusted)?
3. Are the 9 missing tools actually used in the codebase?

---

AI generated by Planning Assistant
Related to #7944

AI generated by Plan Command for discussion #7935

Comments on the Issue (you are @copilot in this section)

• Fixes [plan] Document tool restrictions in included_file_schema.json #7948

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.