For the complete documentation index, see llms.txt. This page is also available as Markdown.
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.
[
{
"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.
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)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.
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
depthtostandardin agent loops. An agent that reaches fordeep_reviewon 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
Last updated