aegisub-mcp

Overview Schema Source Related Servers Discussions Admin

ass_parse_text

Tokenize an ASS line into ordered text segments and override tags, mapping plain characters to raw indices. Use raw text or a document line index for inspection.

Instructions

Tokenise an ASS line into its ordered segments and override tags.

Args: text: a raw ASS Text field (tags included). Use this to inspect a line that is not (yet) in a document. index: 0-based line index in doc_id; the line's current Text field is read from the document. doc_id: document holding index; the current document when omitted. Passing both text and index is an error.

Returns a dict with:

source/index/doc_id which input was used ("text" or "line"). raw, raw_length the line exactly as stored (raw index space). plain_text, plain_length, characters the visible text and, for every visible character, its index in both spaces: {"plain_index": i, "char": c, "raw_index": r}. segments ordered alternating text runs and {...} blocks. A text segment carries text plus start/end (raw indices) and plain_start/plain_end. A block segment carries raw (including braces), inner, block (0-based block number), is_override (True when it holds at least one \ tag; a block without tags is an ASS comment block), the same four offset fields (plain_start == plain_end for blocks) and tags. tags the flat list of every tag in line order, each with name (canonical, lowercase, e.g. kf for \K), argument ("" for valueless tags), raw (exact source text), paren (whether the argument was written in parentheses), is_override and block. Every parsed tag has is_override True because only backslash-prefixed content is parsed as a tag; see the block-level flag for comment blocks. summary per-line flags: blocks, tags, tag_names (histogram), tag_groups (histogram by tag family), has_drawing (drawing mode is still active at the end of the line, i.e. an unmatched \p), drawing_state, has_karaoke, has_transform, has_clip and plain_length. Use tag_names["p"]/tag_groups["drawing"] to detect a drawing that is switched off again by \p0.

Read-only; no snapshot. start/end are raw indices, everything with plain in its name is a plain (visible character) index.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`text`	No
`index`	No
`doc_id`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 12, 2026

TDQS

A4.2/5.0

Behavior4/5

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

With no annotations, the description carries the full burden, and it does disclose the key traits: 'Read-only; no snapshot' tells the agent there is no undo side effect, and the mutual-exclusivity of text/index is flagged as an error. It does not discuss failure modes for a missing index/doc_id, so it is strong but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and args are front-loaded and well organised, but the Returns block is a large enumeration of keys that an output schema (present per context) should already carry, making it redundant bulk for a description. Structure is good; economy is not.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only parser with three optional params, the description covers input selection, offset semantics (raw vs plain index spaces), and the shape of results. Since an output schema exists, the detailed return documentation is more than strictly needed, but nothing an agent needs to call the tool correctly is missing.

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 description coverage is 0%, so the description must compensate, and it does: text is a raw ASS Text field with tags included, index is 0-based on doc_id, doc_id defaults to the current document, and combining both is invalid. This is meaningful semantics beyond the bare schema titles.

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 first sentence gives a precise verb and resource: tokenising an ASS Text field into ordered segments and override tags. This is materially different from siblings such as ass_tag_summary (aggregate) or ass_get_line (retrieval), so an agent can distinguish it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states a concrete when-to-use case ('Use this to inspect a line that is not (yet) in a document') and an explicit misuse condition ('Passing both text and index is an error'). It stops short of naming sibling alternatives for the in-document case, so it is clear but not fully routing.

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

Deploy Server