# Claude and OpenAI tool use

Expose SciSpace endpoints as tools so an agent can research on demand.

## Tool definitions

Four tools cover almost every research agent. Keep it to these — agents choose badly among many
options, and each extra parameter is another thing for the model to get wrong.

```json
[
  {
    "name": "search_literature",
    "description": "Answer a research question from published literature. Returns a synthesized answer with citations. Use for questions about what is known, not for questions about a specific document the user uploaded.",
    "input_schema": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "description": "The research question, in natural language."
        },
        "depth": {
          "type": "string",
          "enum": [
            "standard",
            "high_quality",
            "deep_review"
          ],
          "description": "standard for quick lookups; deep_review only when the user asks for a thorough review, as it takes minutes and costs 60 credits."
        }
      },
      "required": [
        "query"
      ]
    }
  },
  {
    "name": "get_paper",
    "description": "Fetch metadata for one paper by DOI or SciSpace paper id. Use when the user names a specific work and you need its authors, venue, year, or retraction status.",
    "input_schema": {
      "type": "object",
      "properties": {
        "identifier": {
          "type": "string",
          "description": "A DOI such as 10.48550/arXiv.1706.03762, or a pap_ id."
        }
      },
      "required": [
        "identifier"
      ]
    }
  },
  {
    "name": "ask_document",
    "description": "Ask a question about a PDF the user has already uploaded. Returns an answer with page-level citations. Use only for documents in the user's library, never for the published corpus.",
    "input_schema": {
      "type": "object",
      "properties": {
        "document_id": {
          "type": "string",
          "description": "A doc_ id."
        },
        "question": {
          "type": "string",
          "description": "The question about this document."
        }
      },
      "required": [
        "document_id",
        "question"
      ]
    }
  },
  {
    "name": "format_citation",
    "description": "Render a citation for a paper in a named style. Free and fast; prefer it to writing citations yourself, which produces errors.",
    "input_schema": {
      "type": "object",
      "properties": {
        "paper_id": {
          "type": "string",
          "description": "A pap_ id."
        },
        "style": {
          "type": "string",
          "description": "A style short_name such as apa, vancouver, or chicago-author-date."
        }
      },
      "required": [
        "paper_id",
        "style"
      ]
    }
  }
]
```

## Wiring them up

The descriptions carry the routing logic — `search_literature` versus `ask_document` is the choice
agents get wrong most often, so both descriptions say explicitly what they are *not* for.

```python
import anthropic
from scispace import Scispace

scispace = Scispace()
claude = anthropic.Anthropic()

def run_tool(name, args):
    if name == "search_literature":
        s = scispace.searches.create(**args).wait(timeout=300)
        return {"answer": s.answer.text, "citations": [c.model_dump() for c in s.answer.citations]}
    if name == "get_paper":
        return scispace.papers.retrieve(args["identifier"]).model_dump()
    if name == "ask_document":
        chat = scispace.chats.create(document_id=args["document_id"])
        msg = scispace.chats.messages.create(chat_id=chat.id, content=args["question"]).wait()
        return {"answer": msg.content, "citations": [c.model_dump() for c in msg.citations]}
    if name == "format_citation":
        return scispace.citations.create(**args).model_dump()
    raise ValueError(name)
```

> [!warning] Pass the citations through to the user
> Returning only `answer.text` to the model strips the provenance that makes these results worth
> having, and the model will not reconstruct it. Hand back `citations` and render them.

> [!info] Cap depth in the tool layer, not the prompt
> An agent told it may use `deep_review` eventually will. Clamp it in `run_tool` and let the model
> ask — see cost-control.

## Guidance that matters

- **Default `depth` to `standard`** in agent loops. An agent that reaches for `deep_review` on every
  turn will burn a month of credits in an afternoon.
- **Return citations to the model and to the user.** If the agent summarizes away the sources, you
  have rebuilt an ungrounded chatbot.
- **Cap the loop.** Set a per-conversation credit budget and stop.

## Related

searches · cost-control