addDocument

Instructions

Implementation Reference

• src/tools/addDocument.ts:33-53 (handler)

  The main handler function for the addDocument tool. It takes a Backlog client and TranslationHelper, returns a ToolDefinition with name 'addDocument', schema, outputSchema (DocumentItemSchema), and a handler that calls backlog.addDocument(params).

  export const addDocumentTool = (
    backlog: Backlog,
    { t }: TranslationHelper
  ): ToolDefinition<
    ReturnType<typeof addDocumentSchema>,
    (typeof DocumentItemSchema)['shape']
  > => {
    return {
      name: 'addDocument',
      description: t(
        'TOOL_ADD_DOCUMENT_DESCRIPTION',
        'Adds a new document to the specified project.'
      ),
      schema: z.object(addDocumentSchema(t)),
      outputSchema: DocumentItemSchema,
      importantFields: ['id', 'projectId', 'title', 'plain', 'createdUser'],
      handler: async (params) => {
        return backlog.addDocument(params);
      },
    };
  };

• src/tools/addDocument.ts:7-31 (schema)

  Input schema for the addDocument tool defining fields: projectId (number, required), title (string, optional), content (string, optional), emoji (string, optional), parentId (string, optional), and addLast (boolean, optional).

  const addDocumentSchema = buildToolSchema((t) => ({
    projectId: z
      .number()
      .describe(t('TOOL_ADD_DOCUMENT_PROJECT_ID', 'Project ID')),
    title: z
      .string()
      .optional()
      .describe(t('TOOL_ADD_DOCUMENT_TITLE', 'Title of the document')),
    content: z
      .string()
      .optional()
      .describe(t('TOOL_ADD_DOCUMENT_CONTENT', 'Content of the document')),
    emoji: z
      .string()
      .optional()
      .describe(t('TOOL_ADD_DOCUMENT_EMOJI', 'Emoji for the document')),
    parentId: z
      .string()
      .optional()
      .describe(t('TOOL_ADD_DOCUMENT_PARENT_ID', 'Parent document ID')),
    addLast: z
      .boolean()
      .optional()
      .describe(t('TOOL_ADD_DOCUMENT_ADD_LAST', 'Add to the end of the list')),
  }));

• src/types/zod/backlogOutputDefinition.ts:498-512 (schema)

  DocumentItemSchema - the output/response schema for the addDocument tool. Defines the shape of the returned document object with fields: id, projectId, title, plain, json, statusId, emoji, attachments, tags, createdUser, created, updatedUser, updated.

  export const DocumentItemSchema = z.object({
    id: z.string(),
    projectId: z.number(),
    title: z.string(),
    plain: z.string(),
    json: z.string(),
    statusId: z.number(),
    emoji: z.string().nullable(),
    attachments: z.array(DocumentFileInfoSchema),
    tags: z.array(DocumentTagSchema),
    createdUser: UserSchema,
    created: z.string(),
    updatedUser: UserSchema,
    updated: z.string(),
  });

• src/tools/tools.ts:154-164 (registration)

  Registration of addDocumentTool within the 'document' toolset group in the allTools function. The toolset is disabled by default.

  {
    name: 'document',
    description: 'Tools for managing documents.',
    enabled: false,
    tools: [
      getDocumentsTool(backlog, helper),
      getDocumentTreeTool(backlog, helper),
      getDocumentTool(backlog, helper),
      addDocumentTool(backlog, helper),
    ],
  },

• src/tools/tools.ts:60-60 (registration)

  Import statement for addDocumentTool from './addDocument.js' in the tools aggregation module.

  import { addDocumentTool } from './addDocument.js';