Write good descriptions for AI

Good descriptions decide whether an AI picks your service for the right questions and sends the right values. This page shows what to write in each field of AI → Definition, with good and bad examples.

The one rule

Write what a value means. Do not repeat what SpreadAPI already tells the AI: the name, the type, required or optional, the default, the allowed values, the range, and that a percentage is sent as a decimal. All of that is read from the parameter and served automatically.

What only you know: the unit, what a value refers to, what a result stands for, and when the service should not be used.

What the service does

One or two sentences: what it calculates and from what. Start with a verb.

Why: the first names inputs and result, so an AI can match it to a question. "Pricing tool" could mean anything.

When the AI should use it

Name the kind of question, and when not to use it if that is clear.

Why: the third example describes a parameter, which already has its own text and its range.

How the AI should answer

Optional. Say how the result should look: which value comes first, and what belongs in a table or a list. At most 400 characters.

Why: the last example is about when to call, which belongs in When the AI should use it. Assistants usually follow the wish, but the presentation cannot be guaranteed. See AI → Definition.

Example questions

Three to five short questions, the way a user would really ask. Use only values the inputs allow.

Inputs

One short sentence or phrase per input: the unit, what it refers to, and conventions an AI cannot guess.

What an AI needs to know about an input:

• The unit, when it is not in the name: euro or dollar, months or years, net or gross.
• What it refers to: per user, per month, per order.
• The sign convention, when it matters: is a payment positive or negative.
• What to do when the user gives no value, if the answer is not simply the default.

Outputs

Say what the number stands for, with unit and scope.

For an output that is a range, describe the rows and columns. The AI is told that it gets a table and its size; it is not told what the columns mean unless you say so.

Things you do not need to write

• "Send a decimal: 0.05 for 5%." It is added automatically for every percentage input.
• Allowed values and ranges. They are served from the parameter settings.
• "Required" or "optional" and the default.
• Instructions such as "always call this tool". The AI is already told to calculate every number with the service instead of estimating it.

Things to avoid

• Marketing language. An AI needs facts to match a question.
• Rules the service cannot enforce and that are not about its numbers.
• Texts in a language your users do not ask in. Write in the language of your users' questions; names and allowed values stay as they are.
• Promises about results. Describe what is calculated, not what the user should conclude.

A quick check

1. Open AI → Definition and scroll to Summary (Zusammenfassung).
2. Read it as if you knew nothing about the workbook. Could you answer "What do I send, and what do I get?"
3. Fix every Meaning unclear (Bedeutung unklar) mark.
4. Save and publish again, then ask your AI one of the example questions.

Use Suggest all (Alles vorschlagen) for a first draft and improve it with the rules above. See AI → Definition.

For developers and agents

When you describe a service through an account connection:

• update_service: description (what it calculates, at most 500 characters), usage_guidance (when to use it and rules that are not in the numbers), presentation_guidance (how results should be presented, at most 400 characters), usage_examples (questions it answers, at most 10).
• set_parameters: a description per input and output. Mark rates and discounts with "percentage": true or write the cell as "4%"; do not describe the decimal convention in the text.
• allowed_values, min, max, required and default belong in the parameter, not in the description.
• Verify with describe_service: it returns the texts and facts as a caller gets them.

FAQ

How do I write a good description for my service?

Say in one or two sentences what it calculates and from what, starting with a verb. Add when an AI should use it and three to five example questions.

What should I write for an input?

Write what the value means: the unit, what it refers to, and any convention an AI cannot guess. Do not repeat the type, the range or the allowed values, because those are served automatically.

What should I write for an output?

Say what the number stands for, with its unit and scope, for example "Total price per month in euro, after discount, without VAT". For a range, describe the rows and columns.

How many example questions should I add?

Three to five short questions are a good set. Use only values your inputs allow, so the AI does not learn an example that would be refused.

The AI does not pick my service for the right questions. What can I improve?

Make What the service does concrete, fill When the AI should use it with the kind of question, and add example questions phrased the way your users ask. Then save and publish again.

Should I tell the AI in the description how to send percentages?

No. SpreadAPI adds the decimal rule to every percentage input by itself; describe only what the percentage means.

In which language should I write the descriptions?

Write in the language your users ask their questions in. Parameter names and allowed values are not translated.

Can the AI suggestion replace writing descriptions myself?

It gives a good first draft from the names, limits and example values of your service. It cannot know units, business rules or exceptions that are not visible there, so read and correct each draft.

As an agent, how do I check that my descriptions arrived?

Call describe_service for the service. It returns description, usage_guidance, usage_examples and each parameter with its description, limits and hints, as callers get them.