superdoc_list

Create and manipulate bullet and numbered lists. Most actions require a list-item target: {kind:"block", nodeType:"listItem", nodeId:"<id>"}. Exceptions: "create" and "attach" operate on paragraph targets (they turn paragraphs into list items). Find nodeIds via superdoc_get_content({action:"blocks"}): pick listItem blocks for most actions, paragraph blocks for create/attach. CREATE & CONVERT: • "create": make a NEW list from paragraphs. Two modes: mode:"empty" with at:{kind:"block", nodeType:"paragraph", nodeId} converts a single paragraph; mode:"fromParagraphs" with target:{from:{...paragraph block address}, to:{...paragraph block address}} converts a range: ALL paragraphs between from and to become items, so make sure no other content sits between them. Pass a preset ("disc"|"circle"|"square"|"dash" for bullets; "decimal"|"decimalParenthesis"|"lowerLetter"|"lowerLetterParenthesis"|"upperLetter"|"upperLetterParenthesis"|"lowerRoman"|"upperRoman" for ordered) or a custom style. Use "create" to start a fresh list: NOT to extend an existing one (use "attach" for that). • "attach": add paragraphs to an EXISTING list, inheriting its numbering definition. Pass target:{paragraph block address} (or {from, to} range of paragraphs) + attachTo:{kind:"block", nodeType:"listItem", nodeId:"<any item in destination list>"} + optional level:0..8. Use this to extend a list or as the second half of a merge workflow (see "join" below). • "set_type": convert an existing list between ordered and bullet. Pass target:{listItem} + kind:"ordered" or "bullet". Adjacent compatible sequences are merged automatically to preserve continuous numbering. • "detach": convert a list item back to a plain paragraph. Pass target:{listItem}. ITEMS & NESTING: • "insert": add a new list item adjacent to an existing item in the same list. Pass target:{listItem} + position:"before"|"after" + optional text. Use this (NOT superdoc_create) to add items to an existing list. • "indent" / "outdent": bump the target item's nesting level by one (0-8 range). Pass target:{listItem}. • "set_level": jump the target item to an explicit level. Pass target:{listItem} + level:0..8. NUMBERING (ordered lists): • "set_value": restart numbering at the target. Pass target:{listItem} + value:<number> (e.g. value:1 to start over) or value:null to clear a previous override. Mid-sequence targets are atomically split off into their own sequence. • "continue_previous": make the target's sequence continue numbering from the nearest compatible previous sequence (same abstract definition). Pass target:{listItem of the sequence you want to renumber}. Fails with NO_COMPATIBLE_PREVIOUS or INCOMPATIBLE_DEFINITIONS if no matching prior sequence exists. SEQUENCE SHAPE (merge / split): • "merge": merge the target's sequence with an adjacent one into one continuous list. Pass target:{listItem} + direction:"withPrevious" or "withNext". Absorbed items adopt the absorbing sequence's numbering definition, and empty paragraphs between the two sequences are removed so numbering flows continuously. • "split": split the target's sequence at the target item into two independent lists. The target and everything after become a new sequence that restarts numbering at 1. Pass target:{listItem}; add restartNumbering:false to keep the count continuing instead of restarting. EXAMPLES: 1. {"action":"create","mode":"fromParagraphs","preset":"disc","target":{"from":{"kind":"block","nodeType":"paragraph","nodeId":"<firstId>"},"to":{"kind":"block","nodeType":"paragraph","nodeId":"<lastId>"}}} 2. {"action":"set_type","target":{"kind":"block","nodeType":"listItem","nodeId":"<itemId>"},"kind":"ordered"} 3. {"action":"insert","target":{"kind":"block","nodeType":"listItem","nodeId":"<itemId>"},"position":"after","text":"New list item"} 4. {"action":"indent","target":{"kind":"block","nodeType":"listItem","nodeId":"<itemId>"}} 5. {"action":"merge","target":{"kind":"block","nodeType":"listItem","nodeId":"<itemId>"},"direction":"withPrevious"} 6. {"action":"split","target":{"kind":"block","nodeType":"listItem","nodeId":"<itemId>"}} 7. {"action":"set_value","target":{"kind":"block","nodeType":"listItem","nodeId":"<itemId>"},"value":1} 8. {"action":"continue_previous","target":{"kind":"block","nodeType":"listItem","nodeId":"<itemId>"}}. It is categorised as a Read tool in the Superdoc MCP Server, which means it retrieves data without modifying state.

superdoc_list accepts 12 parameters: at, kind, mode, text, force, input, level, style, value, action, dryRun, nodeId. Required: action. The full parameter table on this page comes from the server's own tool schema.

Register the Superdoc MCP server in PolicyLayer and add a rule for superdoc_list: allow, deny, rate-limit, or require approval. Point your MCP client at the PolicyLayer proxy URL and the rule is enforced on every call, before it reaches Superdoc. Nothing to install.

superdoc_list is a Read tool with low risk. Read-only tools are generally safe to allow by default.

Yes. Add a rate_limit block to the superdoc_list rule in your PolicyLayer policy. For example, setting max: 10 and window: 60 limits the tool to 10 calls per minute. Rate limits are tracked per agent session and reset automatically.

Set action: deny in the PolicyLayer policy for superdoc_list. The AI agent will receive a policy violation error and cannot call the tool. You can also include a reason field to explain why the tool is blocked.

superdoc_list is provided by the Superdoc MCP server (@superdoc/mcp). PolicyLayer sits as a proxy in front of this server to enforce policies before tool calls reach the server.