After reviewing the current four tools, I think there are a few new tools worth adding.
1. list_recent_changes
Purpose: list sections updated since a given commit SHA or date, on a given branch.
Why:
- Agents with cached context can ask "anything new in incident-management since last Tuesday?" and refresh only what changed instead of re-fetching everything.
- Contributors can track when their section on
develop gets promoted to main without watching the repo manually.
- Potential SEAL comms. Useful as the basis for monthly changelogs or "what's new" posts.
- General good citizenship for any agent integrated with the MCP: incremental sync instead of full reindex.
2. get_framework_outline
Purpose: given a framework name (e.g. incident-management), return its hierarchical structure: pages, sections, anchors, in document order.
Why:
- Agents helping with incident response shouldn't blind-search. Knowing the structure of
incident-management first lets them fetch sections in their intended order (a playbook is meant to be read sequentially).
- Contributors writing new content need to see what's already covered in their area to avoid duplication. Search returns ranked snippets, not a structural map.
- seal-cli gap:
seal list --branch main shows top-level frameworks. The natural next command would be seal outline incident-management.
3. diff_framework_section
Purpose: section-level textual diff between the same path on two branches.
Why: compare_framework_path answers "did this change?". This tool answers "what changed?", at the section level, in clean prose without MDX markup noise.
Four use cases I can see:
- Maintainers during monthly
develop to main reviews. An agent with MCP access can summarize substantive prose changes in a given playbook in one tool call, instead of the reviewer mentally filtering MDX, JSX, and formatting tweaks out of a file-level GitHub diff. Treats the review as a prose review, not a code review.
- Contributors checking on their sections. Someone who wrote a section months ago wants to see how it has evolved on
develop versus what's live on main, without digging through PR history. seal diff <path> becomes the natural answer.
- Agents using Frameworks as reference data. Incident-response assistants, audit tools, and similar agents need to know not just that their cached guidance has changed (which
list_recent_changes gives them) but what has changed, so they can update their understanding rather than blindly re-fetching.
- Comms about "what's new" updates.
list_recent_changes gives the inventory; this gives the substance to write about.
4. find_related_sections
Purpose: given a section ID, return topically related sections.
Why: Frameworks content cross-references itself heavily, but keyword search doesn't always surface the obvious neighbor.
Still unsure of how to implement this as we can't rely on tags alone since most sections share the same broad tags (e.g. "Security Specialist"). We could make it read the "Related Frameworks" section that is in most of the pages (i would need to add this section to all the pages that are missing it but i think that AI can solve this very easily). Open to other approaches/suggestions.
Proposed PR order
get_framework_outlinelist_recent_changesdiff_framework_sectionfind_related_sections
I've also considered a list_tags tool but I'm unsure of the actual value it can have. Lmk what you think @mattaereal!
After reviewing the current four tools, I think there are a few new tools worth adding.
1.
list_recent_changesPurpose: list sections updated since a given commit SHA or date, on a given branch.
Why:
developgets promoted tomainwithout watching the repo manually.2.
get_framework_outlinePurpose: given a framework name (e.g.
incident-management), return its hierarchical structure: pages, sections, anchors, in document order.Why:
incident-managementfirst lets them fetch sections in their intended order (a playbook is meant to be read sequentially).seal list --branch mainshows top-level frameworks. The natural next command would beseal outline incident-management.3.
diff_framework_sectionPurpose: section-level textual diff between the same path on two branches.
Why:
compare_framework_pathanswers "did this change?". This tool answers "what changed?", at the section level, in clean prose without MDX markup noise.Four use cases I can see:
developtomainreviews. An agent with MCP access can summarize substantive prose changes in a given playbook in one tool call, instead of the reviewer mentally filtering MDX, JSX, and formatting tweaks out of a file-level GitHub diff. Treats the review as a prose review, not a code review.developversus what's live onmain, without digging through PR history.seal diff <path>becomes the natural answer.list_recent_changesgives them) but what has changed, so they can update their understanding rather than blindly re-fetching.list_recent_changesgives the inventory; this gives the substance to write about.4.
find_related_sectionsPurpose: given a section ID, return topically related sections.
Why: Frameworks content cross-references itself heavily, but keyword search doesn't always surface the obvious neighbor.
Still unsure of how to implement this as we can't rely on tags alone since most sections share the same broad tags (e.g. "Security Specialist"). We could make it read the "Related Frameworks" section that is in most of the pages (i would need to add this section to all the pages that are missing it but i think that AI can solve this very easily). Open to other approaches/suggestions.
Proposed PR order
get_framework_outlinelist_recent_changesdiff_framework_sectionfind_related_sectionsI've also considered a
list_tagstool but I'm unsure of the actual value it can have. Lmk what you think @mattaereal!