Research pages

Markdown

Optional research tools, from Roadstar’s research product. Every agent has them, but they aren’t for the business’s own work: a client’s proposal is a doc, not a research page.

request starts a page on a question and costs money with no price up front, so it is always checked.

How to use it

What find_tools sends with these tools, word for word:

Research pages in this workspace: question and thesis pages the reporter writes.

Tools

Tool	What it does	Owner’s yes
pages.list	Pages, newest first	No
pages.read	A page with its content and sources	No
pages.request	Start a research page on a question, in the project the owner names, else the one you file into. A page costs money and has no price up front	Checked
pages.update	Change figures in a page the owner requested, each edit replacing words the page has now; label names the figure	Checked
pages.move	Move a page to another project	Checked
pages.mark	Star or follow a page	No

list

pages.list · Pages, newest first.

Owner’s yes: No. Nothing of the owner’s changes.

Input	Type	Required	Limits
`projectId`	id	no
`title`	text	no	up to 300 characters
`type`	one of `question`, `thesis`	no
`status`	one of `queued`, `running`, `failed`, `published`	no
`offset`	whole number	no	0 or more

Returns:

{
  items: {
    id: string;
    title: string;
    type: "question" | "thesis" | "doc";
    projectId: string;
    projectName: string;
    status: "draft" | "published" | "archived";
    generationStatus: "queued" | "running" | "failed" | "completed" | null;
    updatedAt: string;
  }[];
  nextOffset: number | null;
}

read

pages.read · A page with its content and sources.

Owner’s yes: No. Nothing of the owner’s changes.

Input	Type	Required	Limits
`pageId`	id	yes

Returns:

{
  state: "doc";
  projectId: string;
  organizationId: string;
  agentId: string | null;
  page: {
    id: string;
    title: string;
    type: "doc";
  };
} | {
  projectId: string;
  organizationId: string;
  agentId: string | null;
  errorMessage: string;
  page: {
    id: string;
    slug: string;
    title: string;
    type: "question" | "thesis";
  };
  state: "failed";
  phase?: undefined;
} | {
  projectId: string;
  organizationId: string;
  agentId: string | null;
  page: {
    id: string;
    slug: string;
    title: string;
    type: "question" | "thesis";
  };
  phase: "queued" | "writing" | "researching" | "verifying";
  state: "generating";
  errorMessage?: undefined;
} | {
  page: {
    id: string;
    title: string;
    type: "question" | "thesis";
  };
  projectId: string;
  organizationId: string;
  agentId: string | null;
  state: "unavailable";
} | {
  projectId: string;
  organizationId: string;
  agentId: string | null;
  type: "question";
  author: {
    image: string | null;
    name: string;
  };
  canonicalUrl: string;
  description: string;
  currentRevisionId: string | null;
  id: string;
  isAuthenticated: boolean;
  isFollowing: boolean;
  isStarred: boolean;
  isPublished: boolean;
  model: GeneratedPageDocumentModel;
  publishedAt: string;
  slug: string;
  state: "ready";
  starCount: number;
  wordCount: number;
  page?: undefined;
} | {
  projectId: string;
  organizationId: string;
  agentId: string | null;
  type: "thesis";
  state: "ready";
  id: string;
  slug: string;
  model: {
    artifact: {
      type: "thesis";
      version: 1;
      horizon: "1-2" | "2-5" | "5-10";
      relatedQuestion: {
        id: string;
        title: string;
        slug: string;
      } | null;
      asOf: string;
      assessment: {
        summaryMarkdown: string;
        bodyMdx: string;
        conviction: "low" | "medium" | "high" | "insufficient";
        rationaleMarkdown: string;
        changeConditions: string[];
      };
      pillars: {
        id: string;
        side: "for" | "against";
        title: string;
        explanationMarkdown: string;
      }[];
      articles: {
        date: string | null;
        datePrecision: "day" | "month" | "year" | null;
        stance: "supporting" | "challenging" | "mixed";
        pillarIds: string[];
        relevanceMarkdown: string;
        documentId: string;
        title: string;
        url: string;
        author: string | null;
        imageUrl: string | null;
        confidence: "low" | "medium" | "high" | null;
      }[];
    };
    title: string;
  };
  author: {
    image: string | null;
    name: string;
  };
  canonicalUrl: string;
  description: string;
  currentRevisionId: string | null;
  isPublished: boolean;
  isAuthenticated: boolean;
  isFollowing: boolean;
  isStarred: boolean;
  starCount: number;
  firstPublishedAt: string | null;
  publishedAt: string | null;
  page?: undefined;
}

request

pages.request · Start a research page on a question, in the project the owner names, else the one you file into. A page costs money and has no price up front.

Owner’s yes: Checked. It carries a note for the check to weigh, such as a cost.
Your work: listed on Home.

Input	Type	Required	Limits
`projectId`	id	no
`question`	text	yes	1–2,000 characters
`context`	text	no	up to 4,000 characters

Returns:

{
  pageId: string;
  slug: string;
  generationToken: string;
  status: "queued" | "running" | "failed" | "completed";
}

update

pages.update · Change figures in a page the owner requested, each edit replacing words the page has now; label names the figure.

Owner’s yes: Checked. It changes what’s there.
Your work: listed on Home, with Undo.

Input	Type	Required	Limits
`pageId`	id	yes
`title`	text	no	up to 200 characters
`edits`	list of `{ label, find, replace, was?, now? }`	yes	1–12 items
`edits[].label`	text	yes	1–120 characters
`edits[].find`	text	yes	1–2,000 characters
`edits[].replace`	text	yes	up to 2,000 characters
`edits[].was`	text	no	up to 60 characters
`edits[].now`	text	no	up to 60 characters
`sentence`	object	no
`sentence.before`	text	yes	1–2,000 characters
`sentence.after`	text	yes	1–2,000 characters
`source`	object	yes
`source.label`	text	yes	1–200 characters
`source.href`	text	yes	1–2,000 characters
`quote`	text	no	up to 1,000 characters

Returns:

{
  pageId: string;
  replaced: string;
  published: {
    revisionId: string;
    revisionNumber: number;
  };
}

move

pages.move · Move a page to another project.

Owner’s yes: Checked. It changes what’s there.
Your work: listed on Home.

Input	Type	Required	Limits
`pageId`	id	yes
`projectId`	id	yes

Returns:

{
  id: string;
  projectId: string | null;
}

mark

pages.mark · Star or follow a page.

Owner’s yes: No. It makes something new.
Your work: listed on Home.

Input	Type	Required
`pageId`	id	yes
`action`	one of `star`, `follow`	yes
`enabled`	true or false	yes

Returns:

{
  pageId: string;
  action: "star" | "follow";
  enabled: boolean;
}

Types

Named types in the results above.

type GeneratedPageDocumentModel = {
  artifact: {
    bodyMdx: string;
    charts: {
      description: string | null;
      id: string;
      noteMarkdown: string | null;
      rows: {
        sourceDocumentIds: string[];
        values: (number | null)[];
        x: string;
      }[];
      series: {
        key: string;
        label: string;
        unit: string | null;
      }[];
      title: string;
      type: "bar" | "line" | "area" | "donut";
      xLabel: string | null;
      yLabel: string | null;
    }[];
    dataTables: {
      columns: string[];
      id: string;
      rows: {
        cells: string[];
        sourceDocumentIds: string[];
      }[];
      title: string;
    }[];
    synopsisMarkdown: string;
    timelines: {
      id: "primary_timeline";
      items: {
        analysisMarkdown: string;
        bodyMarkdown: string;
        date: string | null;
        datePrecision: "day" | "month" | "year" | null;
        id: string;
        sourceDocumentIds: string[];
        title: string;
      }[];
    }[];
    version: 1;
    counterViewMarkdown?: string;
    visualizations?: {
      id: string;
      title: string;
      description: string;
      specJson: string;
      sourceDocumentIds: string[];
    }[];
  };
  sources: GeneratedPageDocumentSource[];
  title: string;
}

type GeneratedPageDocumentSource = {
  citationNumber: number;
  crawlStatus: "queued" | "failed" | "idle" | "crawling";
  datePrecision: "day" | "month" | "year" | null;
  id: string;
  hasSnapshot: boolean;
  publishedDate: string | null;
  title: string;
  url: string;
}