Skip to main content
Glama
juriSacchetta

domustudio-mcp-server

by juriSacchetta
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Elenca persone (anagrafica soggetti)

domustudio_list_persone
Read-onlyIdempotent

List people from a Domustudio archive, optionally filtered by condominio, tags, or search query, to retrieve condòmini contacts and per-building counts in markdown or JSON.

Instructions

Elenca le persone dell'anagrafica Domustudio, opzionalmente ristrette a un condominio.

L'API non espone un identificatore per le persone: il record non contiene alcun id, quindi non esiste una lettura per id e non c'è modo di indirizzare una persona singola. Per trovare qualcuno si filtra questo elenco (search_query, oppure condominio_id più una lettura dei risultati).

Args:

  • archivio (string, opzionale): archivio da interrogare

  • condominio_id (number, opzionale): restringe a un condominio (parametro CondGendID). Ottenerlo da domustudio_list_condomini

  • filtro_subentri (1|2|3|4|5): 1 tutti, 2 attivi, 3 ex, 4 contabilità, 5 destinatari comunicazioni. Default 2

  • esercizio_id (number, opzionale): parametro EsercizioID

  • tags_id (number[], opzionale): parametro TagsID

  • search_query (string, opzionale): passato all'API come SearchQuery; la semantica è decisa dall'API, non documentata nello spec

  • order_by (string, opzionale): passato all'API come OrderBy, semantica non documentata

  • pagina (number): pagina 1-based, default 1

  • dimensione_pagina (number): elementi per pagina, default 50

  • tutte_le_pagine (boolean): se true scorre le pagine fino a 50, default false

  • response_format ('markdown' | 'json'): default 'markdown'

Restituisce (json): { "archivio": string, "conteggio": number, // elementi in questa risposta "pagina": number, // prima pagina letta "dimensione_pagina": number, "pagine_lette": number, "ha_altre_pagine": boolean, // euristica: l'API non restituisce un totale, quindi è vero quando l'ultima pagina era piena "prossima_pagina": number, // presente solo se ha_altre_pagine "troncato_al_limite_pagine": boolean, "elementi": [ { "descr": string, "codFisc": string, "piva": string, "indirizzo": string, "cap": string, "citta": string, "prov": string, "email": string[], "pec": string[], "tel1": string, "note": string, "preferenzaPagamentoRate": { "codice": number, "etichetta": string }, ... } ] } I campi enumerativi sono restituiti come { codice, etichetta }. Il formato markdown mostra denominazione, codice fiscale, indirizzo, recapiti; json riporta il record completo.

Usare quando: servono i condòmini di uno stabile, i recapiti di un soggetto, o un conteggio per condominio. Non usare per: i fornitori, che stanno in un'anagrafica separata (domustudio_list_fornitori).

L'API Domustudio è di sola lettura: espone solo tre endpoint GET. Domustudio resta il sistema di registrazione — ogni correzione va fatta da un operatore dentro il gestionale.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
paginaNoNumero di pagina, 1-based (parametro PageNumber dell'API).
tags_idNoId dei tag (TagsID).
archivioNoNome dell'archivio Domustudio da interrogare. Opzionale se ne è configurato uno solo; usare domustudio_list_archivi per l'elenco.
order_byNoOrdinamento, inoltrato all'API come OrderBy.
esercizio_idNoId dell'esercizio (EsercizioID).
search_queryNoRicerca libera, inoltrata all'API come SearchQuery.
condominio_idNoId del condominio (CondGendID). Omesso, l'API restituisce le persone di tutto l'archivio.
filtro_subentriNo1 tutti, 2 attivi, 3 ex, 4 contabilità, 5 destinatari comunicazioni
response_formatNo'markdown' per una sintesi leggibile dei campi principali, 'json' per il record completo.markdown
tutte_le_pagineNoSe true, scorre le pagine successive fino a esaurimento o fino a 50 pagine (il campo troncato_al_limite_pagine segnala il taglio).
dimensione_paginaNoElementi per pagina (parametro PageSize dell'API). Massimo 100.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
paginaYes
archivioYes
elementiYes
conteggioYes
pagine_letteYes
ha_altre_pagineYes
prossima_paginaNo
dimensione_paginaYes
troncato_al_limite_pagineYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.4.0

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial extra context: the whole API is read-only with only three GET endpoints, Domustudio remains system of record so corrections need an operator, and the pagination heuristic (ha_altre_pagine is inferred because the API returns no total) plus the 50-page truncation behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the identifying constraint, then args, return shape, and when/when-not. It is long and the args block partially duplicates a 100%-covered schema, but every section carries useful information and is well ordered.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 11 optional parameters, the output schema, and the annotations, the description covers everything needed: pagination caveats, truncation, format choices, and the critical absence of per-record ids. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it notes search_query and order_by have API-decided, undocumented semantics, and tells the agent to obtain condominio_id from domustudio_list_condomini. It also enumerates filtro_subentri and defaults, though much of that is already in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Elenca le persone dell'anagrafica Domustudio') and immediately clarifies the crucial scope constraint that the API exposes no per-person identifier, so only listing/filtering is possible. It also differentiates from the sibling domustudio_list_fornitori.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'Usare quando' (condòmini di uno stabile, recapiti, conteggi per condominio) and 'Non usare per' (fornitori, in a separate registry named as sibling). Also hints at alternatives for finding a single person (filter this list).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools