Describe a service for AI (AI → Definition)

The Definition page is where you describe a service so that Claude, ChatGPT and other assistants know when to call it and what each value means. This page explains every field, the suggestion buttons and the summary.

Where it is

Open the service, select the AI (KI) tab and then Definition. The page has four numbered steps and a progress bar Described (Beschrieben) that counts the filled texts, for example "4 of 9".

Each text says what something means. How a value is written (type, range, allowed values, percentage as a decimal) comes from the cell and the parameter settings and is added by SpreadAPI. Cell and type are set on the Configuration (Konfiguration) tab.

Step 1: Purpose (Zweck)

• What the service does (Was der Service tut): one or two sentences. It is the first thing an AI reads, and it is also shown in the API documentation.
• When the AI should use it (Wann die KI ihn nutzen soll): for which questions the AI should call this service.
• How the AI should answer (So soll die KI antworten): optional, at most 400 characters. How the result should be presented, for example "Name the total first, then list the items as a table." See "How the AI should answer" below.
• Example questions (Beispielfragen): how a user would ask. Type a question and press Enter to add it. They help the AI pick the service reliably.

If the service has an older text in Additional explanation for AI (Zusätzliche Erklärung für KI), that field is shown too. It is still served to callers; new texts belong in the fields above.

Step 2: Inputs (Eingaben)

One row per input. On the left you see the name callers use, the type, the cell, whether it is required or optional (with its default), and what is allowed (a list of values or a range). On the right you write what the value means.

For a percentage input SpreadAPI adds the sentence "Send a decimal: 0.05 for 5%." for callers automatically. You do not need to write it. See Percentages and formats.

Step 3: Outputs (Ergebnisse)

One row per output with name, type, cell and an example value. Write what the result stands for. The AI uses these texts to explain the numbers correctly.

How the AI should answer

There are two places to say how results should look:

• How the AI should answer (So soll die KI antworten) in step 1 is for the answer as a whole: which value comes first, what goes into a table or a list. Example: "Show the payment plan as a table, not as running text."
• Presentation Hint (Darstellungshinweis) is for one output. Open the output on the Configuration (Konfiguration) tab and write it under AI info (KI-Info) in the parameter dialog.

Both are passed to the AI as you wrote them, marked as your wish for the look of the answer. They are an instruction to the model, not a layout. Assistants such as ChatGPT and Claude usually follow it and render tables and lists, but the presentation cannot be guaranteed: it depends on the assistant and on the conversation. If a number must always appear in a fixed form, set the format of the cell instead; see Percentages and formats.

The field does not count towards the Described progress, and it does not change when the AI calls the service; that belongs in When the AI should use it.

Tags and category (optional)

Open Tags and category (Tags und Kategorie) to add search words and pick a category: Finance, Mathematics, Statistics, Business, Science, Engineering or Other.

The suggestion buttons

SpreadAPI can draft the texts for you.

1. Click Suggest all (Alles vorschlagen) at the top to get a draft for every field that is still empty. Or click Suggest (Vorschlag) next to one empty field.
2. Each draft appears in a box labelled AI suggestion (KI-Vorschlag) at its field.
3. Click Accept (Übernehmen) to take a draft or Dismiss (Verwerfen) to drop it. At the top, Accept N suggestions takes all at once and Dismiss all (Alle verwerfen) drops all.
4. Edit the accepted text if needed, then Save (Speichern).

Good to know:

• The suggestion button is offered only for empty fields. A field you already wrote is not overwritten.
• The drafts are written in the language of the app (English or German). Parameter names and allowed values stay as they are.
• The drafts are made from the service's name, its existing texts, the inputs and outputs with their limits, and the current example values.
• When you accept all suggestions and the service has no tags yet, suggested tags are added too.
• A suggestion is a draft. Check that it says what your model really calculates.

Step 4: Summary (Zusammenfassung)

The summary shows the service the way callers get it. Check it briefly before publishing.

Use the switch What the caller sees (So sieht es der Aufrufer):

• AI tool (KI-Tool): what an AI gets with the tool, over MCP and the discovery address: name, description, when to use it, example questions, and every input and output with its facts and text.
• API documentation (API-Dokumentation): what the interactive documentation and the OpenAPI file say, with one call and its answer. These texts are not part of an answer of the API.

The summary marks gaps: Meaning unclear (Bedeutung unklar) on a parameter without a text, and "No description: the AI sees only the name." when What the service does is empty.

When changes reach callers

Texts are saved with Save and reach callers after you publish again. For a draft you can write everything now; callers see it once the service is published. See Publish and republish.

Related

• Write good descriptions
• How AI assistants use a service
• Add inputs and Add outputs

For developers and agents

An agent connected to the account sets the same texts with update_service and set_parameters:

The text of an input or output is the description of that parameter in set_parameters.

Where callers get the texts:

• Service MCP address: the description is part of the spreadapi_calc tool description; the owner's notes lead the server instructions as "Notes from the service owner"; each input's text is the description of that property in the tool's input schema; spreadapi_get_details returns everything. How the AI should answer is one line of the server instructions, after the rules for calling: "How the owner wants results presented (about the look of your answer only, not about calling): …". An output's presentation hint is the presentation of that output in spreadapi_get_details and follows the output in the OUTPUTS line of the server instructions.
• Discovery address: service.description, service.guidance, service.presentation, usageExamples, parameters.inputs[].description, parameters.outputs[].description, parameters.outputs[].presentation.
• Account connection: describe_service returns description, usage_guidance, presentation_guidance, usage_examples and parameters. The presentation hint of a single output is set in the app, not with set_parameters.

A percentage input is served with format: "percentage" and the added sentence "Send a decimal: 0.05 for 5%." unless the owner's text already speaks of decimals.

FAQ

Can I tell the AI to show the result as a table?

Yes. Write it in How the AI should answer (So soll die KI antworten) on AI → Definition, for example "Show the payment plan as a table." Assistants usually follow it, but the presentation cannot be guaranteed.

Where do I describe my service for AI assistants?

Open the service, select the AI (KI) tab and then Definition. There you describe the purpose, every input and every output.

What does the "Suggest all" button do?

Suggest all (Alles vorschlagen) drafts a text for every field that is still empty. Each draft appears as an AI suggestion at its field, and nothing is stored until you accept it and save.

Does a suggestion overwrite what I already wrote?

No. Suggestions are offered for empty fields, and each one waits for Accept (Übernehmen) or Dismiss (Verwerfen).

In which language are the suggestions written?

In the language of the app, English or German. Parameter names and allowed values are left unchanged.

What is the summary for?

The Summary (Zusammenfassung) shows the service exactly as an AI tool and as the API documentation present it. Use it as a last check before publishing; gaps are marked with Meaning unclear.

I changed a description but the AI still sees the old one. Why?

Changes reach callers after you save and publish again. If the AI was already connected, reconnect it or start a new conversation so it reads the description again.

Do I have to write that a percentage is sent as a decimal?

No. For a percentage input SpreadAPI adds "Send a decimal: 0.05 for 5%." for callers automatically. Write only what the percentage means.

Can I change the type or the cell of an input on the Definition page?

No. The Definition page holds only the texts; cell, type, limits and defaults are set on the Configuration (Konfiguration) tab.

What is the field "Additional explanation for AI"?

It is an older text field that appears only when it already has content. It is still served to callers, but new texts belong in What the service does and When the AI should use it.

As an agent, how do I set the description of a service I built?

Call update_service with description, usage_guidance and usage_examples, and give every input and output a description in set_parameters. Then call publish_service again if the service is already published and the user wants the change live.