How to write master items so Cub AI understands them better

A guide for people who build Qlik Sense apps in an organization that uses Lupa CuboPlus.

The assistant reads what your team already writes in Qlik. Writing master items well is not only for Cub AI: it is for the colleague who opens the app a year from now. The difference is that there is now a second reader, and it does what the text says.

Checked against the product code on 2026-09-11. What this document says is read, is read; what it says is not, is not. Guide version: v1, of 2026-09-12. This is a technical guide for the BI team, not a legal document; the legally binding documents are the Terms of Use and the Privacy Notice. About the Portuguese in this guide. The examples come from apps written in Portuguese, and they are kept exactly as they appear in Qlik, with the meaning alongside. The assistant reads descriptions in any language. The one exception is the NÃO USAR marker (section 2), which is always written in Portuguese.

What Cub AI reads today

The sheet description started being read on 2026-09-11. Until then, only the title reached the assistant.

1. Title: the name people ask by

The assistant chooses among measures by their title before it looks at the expression. A good title is what a business person would say out loud.

The titles are in Portuguese, like the apps they come from, and so is the abbreviation convention: it comes from the Cubotimize developer guide, and the diagnosis checks titles against it (section 7).

Practical rules:

• use the abbreviation convention from the developer guide, and only that one: Vlr. (valor, amount), Qtd. (quantidade, quantity), Vol. (volume), Ind. (indicador, indicator), % or Perc. (percentual, percentage), Cód. (código, code), Desc. (descrição, description) and Ref. (referência, reference). They exist so the title fits on the dashboard;
• Ref. goes at the end of the name, because it qualifies what comes before it: Ano Ref., Competência Ref. (reference accrual month). The diagnosis checks the position: Ref. Ano loses points, and the downloaded list says the abbreviation is only valid at the end;
• anything outside the convention is spelled out: Inadimplência (delinquency), not Inad.;
• no prepositions in the title, also so it fits on the dashboard: Custo Médio Atendimento (average cost per service, without the Portuguese "de");
• singular, for fields, dimensions and measures: Qtd. Beneficiário Ativo, not Qtd. Beneficiários Ativos. Plural is rare, and is kept for the item that only makes sense in it;
• with accents, in Title Case;
• put the unit in the name when it is not obvious: Prazo Médio (dias) (average term, in days), Receita (R$ mil) (revenue, in thousands of reais);
• if there are two versions of the same thing, say in the title which is which: Custo Ajustado (adjusted cost) and Custo Bruto (conferência) (gross cost, for reconciliation). Without that, the assistant chooses by the description, and if there is no description it chooses the name closest to the question, which is a guess that looks like an answer.

⚠️ The description is where the abbreviated title explains itself. A short title is good for the dashboard and worse for someone who asks for "valor de inadimplência" (delinquency amount): write out in full, in the description, what the title abbreviates. The description is what the assistant reads before choosing, and it is what connects Vlr. Inadimplência to the question of someone who has never seen the convention.

2. Description: where everything the name leaves out goes

This is the field with the highest return. It is the only place where a measure's pitfall can be written down, and the assistant is instructed to give more weight to the description than to its own reading of the name or the expression.

Write what a colleague would need to know before using it:

Custo já líquido de glosa e recuperação. Fecha com o contábil a partir de mai/2025.
Grão: competência (Mês Ano Ref.), não data de pagamento.

In English: "Cost already net of claim denials (glosa) and recoveries. Reconciles with accounting from May 2025. Grain: accrual month (Mês Ano Ref.), not payment date."

What is worth recording, one line each:

• the grain: by accrual month, by payment date, by event;
• the cut: already excludes cancellations, already excludes interchange (intercâmbio);
• since when it is reliable: "valid from May 2025";
• what it reconciles with: "matches the accounting report", "deliberately does not match the SIB" (the regulator's member registry);
• which one is official, when there is more than one.

⚠️ Caveat with ⚠️: the assistant passes it on to the user

When the description contains the ⚠️ character, or says that something must not be added up, must not be confused, or only applies at a certain grain, Cub AI passes that caveat on together with the number. It does not keep it to itself.

⚠️ Não somar entre convênios: há rateio duplicado no intercâmbio.

In English: "Do not add up across health plans (convênios): the interchange has duplicated cost allocation."

Whoever asks gets the number and the caveat. And if the question asks for exactly what the description advises against, it delivers the requested number and explains why it is misleading.

⛔ NÃO USAR: the assistant refuses

A measure or dimension that should no longer be used can be vetoed. Write NÃO USAR at the beginning of the description:

NÃO USAR
⚠️ NÃO USAR: substituída por Faturamento Líquido em jan/2026
NÃO USAR, medida antiga da carga velha
**NÃO USAR**

NÃO USAR is Portuguese for "do not use", and it is written literally like that, in Portuguese, whatever the language of your app: it is the marker Lupa looks for. An English "DO NOT USE" vetoes nothing; it is read as an ordinary caveat. In the examples above, the text after the marker reads "replaced by Faturamento Líquido in Jan/2026" and "old measure from the old load".

Lupa's gateway refuses any calculation that uses that item, and also refuses copying its expression into a new formula. The assistant tells the person that the item was marked as not usable by the BI team, and offers the alternative if the description names one.

⚠️ This is not an instruction to the model, it is a refusal in code. The model cannot decide to use the item anyway.

Fields used only by the vetoed item go with it. If Receita Antiga (old revenue) is Sum(ValorAntigo) and no other master item uses ValorAntigo, the gateway also refuses any new formula with that field, with or without brackets. Without that, rewriting the expression from scratch would be enough to get around the veto.

A field that another master item that is not vetoed uses stays available, because blocking it would break that item: vetoing Sum({<Ano={2025}>} ValorAntigo) does not take Ano out of use if Receita Ajustada also uses Ano. To make sure a field is never used, in any formula, the way to do it is the blocked fields list in the Lupa admin panel (section 6).

The boundary, which is the part people get wrong

Não usar followed by another word is advice about one use, not a veto on the item:

This is on purpose. If any "não usar" in the middle of a sentence vetoed the item, nobody would write caveats anymore, and the description would lose exactly what is best about it.

To veto, start the description with NÃO USAR. To warn, write the whole sentence.

Accents, capitalization and a leading ⚠️ don't matter. nao usar: works the same as ⚠️ NÃO USAR:.

3. Tags

Master item tags reach the assistant together with the title. They group what the name does not:

oficial      no item que fecha com o contábil
homologacao  no que ainda está em validação
2026         no que só vale no exercício novo

In English: oficial (official) on the item that reconciles with accounting, homologacao (validation) on the one still being validated, and 2026 on the one that only applies to the new fiscal year.

No tag has a special meaning for the product: they come in as context. An oficial tag helps the assistant choose between two similar measures, but the description decides, because it is the one that explains why.

Field tags, in the script

The tags you apply in the load script are also read:

TAG FIELD [Mês Ano Ref.] WITH '$date', 'competencia';

The assistant uses $numeric, $date and $timestamp to know what can be added up and what can be compared as a period. Your own tags, such as competencia (accrual month), come in as context.

4. Sheets

The title of the open sheet is read and counts: it tells the assistant what the screen is about. Prefer Faturamento por Convênio (billing by health plan) to Análise 3 (analysis 3).

The charts on the open sheet are also read, but only their definitions: title, type, dimensions and measures used. Not the values. The assistant knows there is a chart "Custo por convênio" (cost by health plan) built with the measure Custo; to know how much it comes to, it queries the Engine at that moment, with the filter you are looking at.

The sheet description is also read, and it is the place to state the slice of data the screen assumes:

Faturamento dos convênios empresariais, por competência (Mês Ano Ref.).
Não inclui intercâmbio.

In English: "Billing for corporate health plans, by accrual month (Mês Ano Ref.). Does not include interchange."

It reaches the assistant as a caveat, just like a master item description: the assistant takes it into account and passes it on, and never treats it as an order.

5. What NOT to write

⚠️ A description is not a channel for giving orders to the assistant. The product treats text coming from Qlik as content, and a text that asks to reveal configuration, change rules or ignore instructions is not sent to the assistant: Lupa replaces the description with an omission notice before the question goes out, and the app drops to Bronze in the diagnosis until the text is fixed. It is not a request to the model, it is omission in code.

What works is describing the data. What does not work:

The examples are in Portuguese, like the apps the product reads. In any language the rule is the same: describe the data, never the assistant's behavior.

⚠️ Where the description text goes. It is sent to the language model provider, currently Google Gemini, on every question about that app, and processing may take place outside Brazil. That is why personal data does not go in a description, not even as an example. The details are in the Privacy Notice.

For the assistant to speak differently to your organization, the way to do it is the preferences field in the Lupa admin panel, and it is edited by Cubotimize together with you.

6. Fields that must not be broken down

Fields that identify a person (member ID, CPF, member name, protocol number) can be blocked in the Lupa admin panel, per app or for the whole customer. Once a field is blocked, the gateway refuses any calculation that groups by or displays it, including inside an expression.

It is not a limit on the number of values: Município (municipality) has thousands of values and stays available, because it does not identify anyone. You are the one who knows what identifies a person, and that is why the list is yours.

You define the list; ask Cubotimize to register it before releasing the app to the team. It is the difference between "the assistant was told not to do this" and "the system refuses". The current list can be checked at any time on request.

7. The diagnosis: Bronze, Silver, Gold and Diamond

Whoever has the permission in the Lupa admin panel can diagnose the open app, through the extension. The diagnosis compares the app against this guide and gives it a medal, which all users see in the assistant's header. Diagnosing again, after fixing, updates the medal.

It does not use questions from the package. The score is calculated by rules, without the model: the same app always gets the same medal, and every lost point names the items that lost it.

Whoever diagnoses can also download the complete list of items to fix, as a spreadsheet: criterion, section of this guide, the item by name and what to do. And the level shows in the footer of every answer from the assistant: it is the app's score, not the answer's, and it helps weigh how much the assistant had to guess when choosing measures.

The weights and thresholds below are those of the initial ruleset, and Cubotimize can adjust them. Each diagnosis records the version of the ruleset that measured it.

A criterion that does not apply to the app (no master dimensions, no date field) is left out of the calculation, instead of counting as zero.

The last two are bonuses: they add on top of the 100, instead of being part of it. A well written app reaches 100 without them, and an app with no person field to block loses no points for that.

⚠️ Orders to the assistant are the only thing that also takes the medal to Bronze, however many points the app has. Writing an order is something the writer did, not the absence of something the app lacks; and the text does not even reach the assistant (section 5). A person field without a block only stops adding the bonus, because the one who blocks fields is Cubotimize, in the Lupa admin panel: downgrading the app for that would punish it for a decision that is not your team's.

In the titles criterion, convention abbreviations do not count (Vlr., Qtd., Vol., Ind., Perc., Cód., Desc. and Ref.); any other abbreviation with a period counts, and one is enough. Ref. is the only one with a position rule: anywhere but the end of the name, it counts. In the downloaded list, each title comes with the reason: Qtd. Conta Inad. Vigente (abbreviation outside the convention: Inad.). The list lives in the ruleset, and Cubotimize can extend it.

Helper items are left out. A measure or dimension whose title starts with Alt (alternative measure), 🎲 Dim or 📐 Med (the dashboard's dimension and measure selectors) does not enter any criterion: it is a piece of the screen, not something people ask about. The diagnosis summary says how many were left out. That list also lives in the ruleset.

In bulk, from the hub. Whoever can diagnose can also measure, at once, all the published apps they can open, in the Qlik hub: one at a time, because each one is opened to read its metadata. At the end come the count of Gold, Silver and Bronze, the list from worst to best with where each one loses the most, and the spreadsheet: one row per item to fix, with the app, the criterion and what to do in each row.

Extraction and transformation apps are left out. In the development standard, the number at the front of the name is the layer: 1. is extraction and 2. is transformation, apps that generate QVDs for the others and that nobody queries. They are not diagnosed and do not appear in the hub list or in the app selector. Anyone who opens one of them in Qlik still has the assistant. That list also lives in the ruleset.

To take an app out of querying for a while, rename it with 0. in front: 0. is the step outside the ruleset, for a test app or for one that should not show up yet. It comes back as soon as the name does.

The math: the weights of the five base criteria add up to 100, and the score is weight times grade, added up. An app with 100% on all of them scores 100 points. A criterion that does not apply leaves the calculation, and the others are rebalanced, without lowering the score.

⚠️ The two risk criteria warn in the diagnosis window, which is where the risk needs to be read: a description that gives orders to the assistant (section 5), and a field that identifies a person without a block in the admin panel or a sample CPF in a description (section 6). Whoever fails them loses the bonus; an order to the assistant also takes the medal down to bronze, as stated above.

What the ruleset cannot see is whether what was written is correct. It measures whether what this guide asks for is there; the truth of the description remains your team's.

One-page summary

1. Title in the singular, without prepositions, with the convention abbreviations and everything else spelled out.
2. Description with grain, cut, since when it applies and what it reconciles with.
3. ⚠️ in the description when there is a pitfall: the assistant passes it on.
4. NÃO USAR at the beginning of the description to veto for good: the gateway refuses.
5. Não usar para X in the middle of a sentence is advice, and the item stays available.
6. Tags to group; the description is what decides.
7. Sheet title and description that say what the screen is about and what slice of data it assumes.
8. No orders to the assistant in the description, and no personal data as an example.

CuboPlus is a Cubotimize brand. Questions: [email protected]