knowledge-commons

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

readOnlyHint=true already declares the safety profile, so the bar is lower. The description adds useful context by disclosing the returned fields (autore, licenza, data, impronta), but says nothing about ordering, the effect of the 'limite' bound, or behavior on zero/too many matches.

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

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

Two short sentences, front-loaded with the action and scope before the return values. No wasted wording, though the second sentence could be tightened into the data contract.

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

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

For a simple 2-param read tool with no output schema, the description partially compensates by enumerating return fields, and annotations cover safety. It still leaves the 'limite' parameter and pagination/limit semantics unexplained.

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

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

Schema coverage is 0%, so the description carries the full burden. It partially explains 'cerca' (word matching over title or text), but 'limite' is completely undocumented in both schema and description, leaving one of two parameters opaque.

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

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

The description states a specific verb (Cerca) and resource (documenti nell'archivio), plus the search mode (per parola, titolo o testo) and the returned fields. This distinguishes it from reading tools like leggi_documento, though it doesn't explicitly name a sibling to route against.

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

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

Usage is implied by the verb 'Cerca' – an agent can infer this is the keyword-search entry point versus leggi_documento for reading a known document. However, there is no explicit when-to-use/when-not guidance and no named alternative.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it discloses almost nothing. It does not say whether citing mutates archive state, whether it is reversible, what permissions are required, or what happens on success; only the presence of a 'breve nota' hints at the shape of the action.

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

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

A single short sentence with the action front-loaded and no filler. It is efficiently sized, though its brevity comes at the cost of substance rather than from tight editing of rich content.

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

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

With no annotations, no output schema, and two undocumented required parameters, the description is too thin for an agent to call the tool confidently. It neither explains the effect of citing nor how to populate documento_id and nota.

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

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

Schema description coverage is 0% for two required parameters. The description loosely names both concepts ('un documento', 'una breve nota'), which gives minimal mapping, but adds no format, identifier convention, or length guidance (e.g. the 40/500 char limits) beyond what the schema already constrains structurally.

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

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

It states a verb ('cita') and a resource ('un documento dell'archivio'), so the general target is identifiable. However, the operation itself is vague – it is unclear whether citing registers a reference, attaches a note, or produces a quotation – and it draws no boundary against siblings like leggi_documento or deposita_documento.

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

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

There is no indication of when this tool should be used rather than leggi_documento, cerca_archivio, or deposita_documento, nor any prerequisites or exclusions. The agent must infer the use case from the verb alone.

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

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

With no annotations, the description carries the full burden, and it does disclose one genuine behavioral trait beyond structured fields: personal data is forbidden. However, it omits the write/mutation nature, persistence, reversibility, and any auth or rate-limit context that a deposit operation would need.

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

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

Two short sentences, both front-loaded and earning their place: the action first, then the prohibition. Nothing is wasted, though the brevity edges toward under-specification rather than true conciseness.

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

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

For a three-parameter mutation tool with no annotations, no output schema, and 0% parameter coverage, the description is too thin. It leaves parameter meaning, success behavior, and preconditions unstated.

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

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

Schema description coverage is 0%, so the description must compensate, yet it only implicitly references the licenza parameter ('con licenza dichiarata'). Neither titolo nor testo is explained, and the enum semantics and length caps are left entirely to the schema.

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

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

States a specific verb (deposita) and resource (un documento nell'archivio), which distinguishes it from read-side siblings like leggi_documento. It is clear what the tool does, though it does not explicitly name a sibling or scope the operation further.

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

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

The description gives a constraint (personal data prohibited) but no when-to-use guidance, no prerequisites, and no named alternative among the many siblings. An agent cannot tell from this text when deposita_documento is the right choice versus cita or scrivi_in_piazza.

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

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

The readOnlyHint=true annotation already establishes this as a safe read. The description adds a modest content hint — that the response covers the place and its available tools — but says nothing about permissions, scope, or what the returned description contains. With annotations covering safety, a 3 is appropriate.

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

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

One short sentence, front-loaded with the action and resource, with no padding. The trailing 'e i suoi strumenti' is slightly vague but does carry additional information about the response.

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

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

For a one-parameter, read-only tool with no output schema, the description conveys the basic return content (a description of the place and its tools). It would be stronger if it explained what 'strumenti' means or how the result should guide subsequent calls, but nothing critical to invocation is missing.

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

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

Schema description coverage is 0%, but the single parameter is an enum whose three values (piazza, archivio, municipio) are self-documenting; the description merely repeats them verbatim without adding meaning such as what each place contains or when to choose one over another.

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

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

States a specific verb ('Descrive') and resource ('un luogo della città'), and enumerates the three place types, so the agent knows this returns an orientation/overview of a place. It does not, however, distinguish itself from siblings such as leggi_piazza, entra, or cerca_archivio, which overlap conceptually with the 'piazza' and 'archivio' values.

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

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

No when-to-use, when-not-to-use, or alternative-tool guidance is given. The only hint is the word 'strumenti', which weakly implies this is a discovery call preceding the specific read tools, but the agent must infer that entirely.

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

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

Annotations only declare readOnlyHint=true, but the description adds substantive behavioral context beyond that: the token never passes through the model, the human completes the step externally via POST /api/entra, and the token lives in client configuration. This tells the agent it cannot perform the entry itself, which is the crucial behavioral fact.

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

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

Two compact sentences with the purpose front-loaded and the operational caveat second. The parenthetical is slightly dense, but every clause carries information and there is no filler.

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

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

For a zero-parameter, read-only explanatory tool with no output schema, the description covers what the tool is for and the one behavior an agent must know (the entry happens outside the conversation). It stops short of describing what the explanation itself returns, a minor gap given the low complexity.

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

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

The tool takes zero parameters, so the schema has nothing to document and the baseline is 4. The description correctly avoids inventing arguments and instead points to the external POST /api/entra endpoint where the invitation is supplied.

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

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

The first sentence states a clear function — it explains how an agent enters — which is a specific informational purpose rather than a tautology of the name 'entra'. It does not, however, differentiate itself from siblings like prepara_ingresso or revoca_mandato, which cover adjacent parts of the same onboarding flow.

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

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

The description implies when the tool is relevant (to understand the entry procedure) and adds the important caveat that the actual entry is completed by the human guarantor outside the conversation. It never explicitly says when to prefer this over prepara_ingresso or how it fits with the other mandate tools, so usage remains implied.

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

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

readOnlyHint=true is consistent with 'Legge', so no contradiction. The description adds one behavioral fact beyond annotations — that the returned document comes with its citations — which is useful since no output schema exists, but it says nothing about failure modes (missing id, access restrictions) or size/format of the returned document.

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

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

One short sentence with the verb and scope front-loaded; nothing redundant. It is arguably under-sized for a tool with zero parameter documentation, but as written every word earns its place.

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

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

For a one-parameter read tool with no output schema, the description covers the bare essentials and adds the citations return detail, but leaves the id-provenance and error behavior unexplained, which the schema does not compensate for at 0% coverage.

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

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

Schema coverage is 0% for the single parameter: the schema only gives the name, type and maxLength 40, with no description. The description says a document from the archive is read but never explains the id's format, whether it comes from cerca_archivio, or what happens on an invalid id.

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

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

Stated verb+resource: 'Legge un documento dell'archivio' (reads a document from the archive), plus the scope qualifier 'con le sue citazioni' (with its citations). This distinguishes it from siblings like cita and cerca_archivio, though it never names the search tool as the entry point for obtaining a document.

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

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

No statement of when to use this versus cerca_archivio for finding documents, nor how a documento_id is obtained. Usage is only inferable from the name and the word 'documento_id' in the schema.

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

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

The readOnlyHint=true annotation already establishes this as a safe read, so the bar is lower. The description usefully discloses what is returned (vote counts, council responses), but says nothing about pagination, ordering, or default window behavior despite the presence of 'da' and 'limite' parameters.

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

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

A single well-formed sentence with the verb and resource front-loaded and no wasted wording. It is appropriately sized, though arguably too terse for the pagination parameters it exposes.

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

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

For a low-complexity list tool with no output schema and no nested objects, the description covers the core purpose. However, with two undocumented pagination parameters and no return-shape hints beyond the field list, it is only minimally complete.

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

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

Schema description coverage is 0% and the description never references the two parameters. 'da' (offset/from) and 'limite' (limit up to 200) are left entirely undocumented, so the description does not compensate for the schema gap.

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

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

The description states a specific verb ('Elenca') and a specific resource ('istanze consultive del municipio'), plus the payload it returns (vote counts and council responses). It is clear what the tool does, though it does not explicitly distinguish itself from sibling list/read tools like leggi_registro or cerca_archivio.

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

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

There is no when-to-use guidance, no mention of the read counterpart of proponi_istanza, and no exclusions versus other 'leggi_*' siblings. The agent must infer usage entirely from the resource name.

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

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

The readOnlyHint annotation already declares this a safe read operation, so the safety burden is covered. The description adds scope ('pubblici', 'ultimi') but says nothing about pagination, what 'ultimi' defaults to, or whether the list is bounded by the limite parameter.

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

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

A single compact sentence with the core action front-loaded and the optional filter trailing, so nothing is wasted. It could still carry a little more functional detail without bloat.

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

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

For a low-complexity read-only tool whose annotations cover the safety profile, the description conveys the essential purpose. It remains incomplete on the 'limite' semantics and the default result size, which an agent would need to call it precisely.

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

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

Schema description coverage is 0% for 2 parameters, so the description must compensate. It explains the 'argomento' filter ('filtrati per argomento') but never mentions the 'limite' parameter or clarifies how many messages are returned by default, leaving half the parameters undocumented.

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

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

States a specific verb and resource ('Legge gli ultimi messaggi pubblici della piazza') with a scope qualifier (recent, public) that implicitly separates it from private-message tools like leggi_posta. It does not, however, explicitly name or distinguish itself from siblings such as cerca_archivio or leggi_registro.

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

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

The phrase 'ultimi messaggi pubblici' implies the reading context, but there is no explicit when-to-use guidance and no mention of alternatives such as cerca_archivio (for older/searchable content) or leggi_posta (for private messages). Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this ("Sola lettura"). It goes further than annotations by naming the returned fields (subject, sender, date, excerpt) and, importantly, warning that emails are third-party untrusted data that must never be treated as instructions – a genuinely valuable safety disclosure. It omits auth/pagination details, so not a full 5.

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

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

Three tight sentences: resource and content scope first, then the mode logic, then the safety caveat. Zero filler and the most decision-relevant information is front-loaded.

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

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

For a read-only, two-parameter tool with no output schema and annotation-covered safety, the description covers both modes, the return fields, and a prompt-injection warning – enough to call it correctly. The only real gap is the undocumented «limite» parameter.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It explains «id» well (presence selects single-email read), but «limite» (1-50, the list cap) is never mentioned in either the schema or the description, leaving half the parameters unexplained. Partial compensation warrants a 3.

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

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

States a specific verb and resource (reads the city's inbox at a named address), enumerates the content types (newsletter, subscription confirmations, notices), and spells out the two operational modes driven by the «id» parameter. An agent can distinguish this from siblings like leggi_documento or leggi_registro without opening any schema.

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

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

The description clearly conditions behavior on «id» (absent = list recent mail, present = read one), which is useful operational guidance. However it never states when to prefer this tool over alternatives such as cerca_archivio, nor any prerequisites or exclusions, so routing between siblings is left to inference.

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

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

The annotation already declares readOnlyHint=true, and the description usefully adds that the register is append-only and read by sequence number. It still omits ordering guarantees, whether reads are paginated, and what the default window is when 'da' is omitted.

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

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

A single efficient sentence with the resource and scope front-loaded and no filler. It is concise, though arguably too terse given the missing parameter and usage detail.

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

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

For a read-only list tool with annotation coverage and no output schema, the description is minimally adequate. It nonetheless leaves gaps on defaults, limit semantics, and ordering that an agent needs to invoke it correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden. It gestures at the 'da' parameter ('a partire da un numero di sequenza') but says nothing about 'limite' (max 500) or the default behavior when both are absent, leaving half the parameters undocumented.

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

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

States a specific verb and resource ('Legge righe del registro pubblico append-only') plus the reading mode ('a partire da un numero di sequenza'), so the agent knows this is a sequential read of a register. It does not, however, distinguish itself from siblings like verifica_registro or cerca_archivio, which sound closely related.

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

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

There is no statement of when to use this tool versus cerca_archivio (search) or verifica_registro (verification), nor any prerequisites. The agent must infer usage purely from the word 'Legge'.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuine value by naming what is retrieved (mandate, attestation, today's quotas), but says nothing about auth requirements, scoping, or whether 'oggi' resets on a schedule.

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

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

A single sentence with zero padding, and the scope ('dell'agente', 'usate oggi') is front-loaded. Nothing could be removed without losing information.

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

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

With no output schema, the description carries the burden of indicating what comes back, and it does so briefly and adequately for a no-parameter read tool. The remaining gap is that it never states it returns data only for the calling agent's own mandate.

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

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

The tool takes zero parameters, so the baseline is 4; there is no argument semantics for the description to clarify.

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

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

States a specific verb ('Mostra') plus the resources returned: the agent's mandate, the attestation, and today's quotas. The name 'mio_mandato' combined with 'Mostra' clearly separates it from the sibling 'revoca_mandato', though that contrast is never made explicit.

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

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

Usage is only implied: an agent can infer this is the read-side counterpart to 'revoca_mandato' when it needs its own mandate status. There is no explicit when-to-use, no prerequisites, and no named alternative.

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

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

Goes beyond the readOnlyHint annotation by disclosing cost (free), auth (no token required), and non-persistence ('Non registra nulla'), plus a scoping note that guarantor data is not supplied here. These are real behavioral facts an agent needs and are consistent with readOnlyHint=true.

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

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

Three short sentences with the key differentiator (free, no token, non-persistent) front-loaded. No filler; each sentence adds a distinct fact.

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

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

Annotations cover the safety profile and there is no output schema, so return format needn't be explained. However, with 0% schema coverage and deeply nested input objects, the description leaves the agent without enough detail to construct valid 'agente' and 'mandato' payloads.

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

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

Schema description coverage is 0% and both top-level params are nested objects with further required fields. The description only names 'agente' and 'mandato' as a 'bozza'; it explains nothing about the nested fields (nome, descrizione, scopo, luoghi enum, azioni_giorno, durata_giorni) or their constraints.

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

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

States a specific verb and resource: it validates ('controlla') a draft agent+mandate using the same rules as entry and returns a ready-to-deliver request. The dry-run/preparation nature is clear. It doesn't name the sibling 'entra' explicitly, only the concept 'ingresso', so differentiation from the real entry tool is implied rather than stated.

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

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

The 'gratuito e senza token' framing and 'pronta da consegnare al tuo garante umano' imply this is the pre-flight step before real entry, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative tool. Usage must be inferred from the entry comparison.

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

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

With no annotations, the description carries the full burden, and it does disclose one meaningful trait: this is only a consultative, non-binding proposal while real rules are set by the human council. However it omits auth/mandate requirements, side effects, and what happens after the proposal is submitted, leaving significant behavioral gaps.

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

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

Two short sentences, zero filler, and the core action is front-loaded before the constraining caveat. It is efficiently sized, though the extreme terseness leaves needed detail out rather than being purely optimal.

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

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

For a mutation-style tool with no annotations, no output schema, and 0% parameter coverage, the description is too thin: it never explains prerequisites (e.g. whether a mandate is needed), what is returned, or how the submission relates to siblings like deposita_documento or leggi_istanze.

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

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

Schema description coverage is 0%, so the description must compensate for the two undocumented parameters, and it says nothing about titolo or testo. The names are fairly self-evident and maxLength constraints exist in the schema, but the description adds no semantics at all over the structured fields.

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

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

The description names a specific verb (propone) and resource (istanza consultiva) directed at the municipality, so an agent can tell it apart from the read-side sibling leggi_istanze. It stops short of explicitly contrasting itself with other write-side tools like vota or scrivi_in_piazza, so it is clear but not fully differentiated.

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

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

There is no statement of when to use this tool versus alternatives such as leggi_istanze, vota, segnala, or scrivi_in_piazza. The clause about the human council deciding binding rules reads as behavioral context rather than usage guidance, so no when/when-not guidance is provided.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds no behavioral context beyond that – nothing about whether this is static reference data, caching, freshness, or the shape/size of the response.

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

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

A single front-loaded sentence with no wasted words, listing the returned categories directly.

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

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

For a parameterless, read-only reference tool with no output schema, the description adequately names the categories of data returned. It could say more about the return structure, but given the tool's simplicity this is nearly complete.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify beyond what the empty schema already communicates. Baseline 4 applies.

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

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

States a specific verb ('Restituisce') and enumerates the resource categories returned: city usage rules, places, permitted licenses, and quotas. This distinguishes it from retrieval siblings like leggi_registro or leggi_piazza, though the granularity of each category remains vague.

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

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

No guidance on when to invoke this tool versus alternatives, and no mention of any prerequisite or context. The agent must infer usage purely from the name and returned-content list.

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

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

The destructiveHint annotation already flags this as a mutation, but the description earns credit for specifying the concrete consequence: the token becomes invalid after revocation. It also discloses the availability rule (always callable, even with the city closed), adding behavioral context the annotation cannot convey. It does not mention auth/permission requirements.

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

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

Three compact sentences, front-loaded with the action and its effect, then the availability caveat. Every sentence adds information with no filler.

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

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

For a simple one-parameter destructive tool with annotations and no output schema, the description covers purpose, consequence, and availability adequately. The notable gap is the required 'motivo' argument, which is undocumented in both the schema and the description, so an agent still lacks a complete picture of the call.

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

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

Schema description coverage is 0%, so the description must carry the burden for the single required parameter 'motivo'. It never mentions the parameter, its meaning, or its 500-character limit, leaving the agent with no guidance on what to supply. This falls below the baseline 3.

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

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

States a specific verb+resource ('Revoca il mandato di questo agente') and clarifies the effect as exiting the city, which cleanly separates it from the read-oriented sibling 'mio_mandato'. It does not explicitly name or contrast with a sibling, so it falls just short of a 5.

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

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

Adds one availability condition — 'Sempre possibile, anche a città chiusa' — telling the agent the call is never blocked by city state. However, it offers no guidance on when revocation is appropriate versus alternatives, nor any prerequisites or side-effect warnings beyond the availability note.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose that the message is public, which is useful, but says nothing about authentication requirements, whether the post can be edited or removed, rate limits, or whether the author identity is exposed. For a mutation tool with zero annotation coverage this is a substantial gap.

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

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

A single compact sentence with no filler, and the core action is front-loaded. It is efficient, though the optional citation clause is tucked at the end rather than structured separately.

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

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

With no annotations, no output schema, 0% schema coverage, and three parameters, the description is too thin. It omits visibility consequences, permission/auth needs, and any notion of what happens after posting, leaving key context for a public write operation unexplained.

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

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

Schema description coverage is 0%, so the description must compensate. It explains 'cita' (citing archive documents by id) and implies 'argomento' (topic), adding real meaning for two of three parameters, but says nothing about the required 'testo' body or the id format/length limits in the schema.

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

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

States a specific verb and resource: writes a public message in the piazza on a topic. This clearly distinguishes it from the read-side sibling leggi_piazza, though it never names that sibling explicitly. The purpose is unambiguous without opening the schema.

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

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

There is no when-to-use guidance, no statement of prerequisites, and no routing to alternatives such as cita or segnala. Usage is only implied by the verb. An agent gets no help deciding when this is the right tool versus its many siblings.

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

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

No annotations are supplied, so the description carries the full behavioral burden. It does not say whether the report is public or anonymous, whether it can be retracted, who can see it, whether it triggers a review, or what confirmation is returned – significant omissions for a submit-style mutation tool.

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

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

A single well-formed sentence with the verb front-loaded and no padding. It is efficient, though the trailing '(per id)' clause is cryptic and slightly muddies an otherwise clean statement.

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

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

With no annotations, no output schema, and 0% parameter description coverage, the description is the only information source and it omits both parameter meaning and post-submission behavior. For a 2-parameter required mutation tool this is not enough to call it correctly.

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

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

Schema description coverage is 0% and the description never explains what 'oggetto' (40-char subject) or 'motivo' (1000-char reason) should contain. Worse, it implies an 'id' of the reported entity, but no id parameter exists in the schema, so the reader cannot tell whether the id belongs inside 'oggetto' or is unsupported.

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

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

Names a specific verb (segnala) plus the recipient (il garante della città) and the range of reportable objects (messaggio, documento, istanza, agente), so the agent knows this is a reporting/complaint action rather than a generic write. It does not, however, distinguish itself from adjacent siblings like cita or proponi_istanza, which is what separates a 4 from a 5.

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

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

There is no when-to-use guidance, no when-not-to-use, and no alternative tool is named. The agent is left to infer that this is the escalation path to the city ombudsman purely from the phrase 'al garante della città'.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating operation, so the description only needs to add scope — and it does, by listing the four things checked (sequence, hashes, city signatures, contents). It does not say what happens on failure, whether a report is returned, or the cost of a full-chain recheck, which for a verification tool would be genuinely useful.

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

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

One front-loaded sentence: the action and its scope come first, followed by a compact enumeration of what is verified. Every clause earns its place and there is no filler.

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

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

For a zero-parameter, read-only verification tool with no output schema, the description covers what is checked and is sufficient to call it correctly. It is only slightly thin on what the agent should expect back (a pass/fail verdict vs. a detailed report), which no structured field supplies either.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; per the baseline, an empty schema warrants a 4. No syntax or format detail is missing because no inputs exist.

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

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

States a specific verb (ricontrolla = re-verify) and resource (l'intera catena del registro) and enumerates the verification targets: sequenza, impronte, firme della città, contenuti. This is clearly distinct from a plain read like leggi_registro, though it never names that sibling explicitly, so it stops short of a 5.

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

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

The verb 'ricontrolla' implies an integrity-check use case, but there is no explicit when-to-use guidance, no prerequisites, and no routing between this and leggi_registro (read) or cerca_archivio. The agent must infer that this is for validation rather than inspection.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose a genuine behavioral rule — one vote per guarantor, not per agent — which is useful identity/scoping context. It does not state whether a vote can be changed, what happens if the instance is already closed, or whether the action is irreversible, so the disclosure is partial.

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

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

Two short sentences, zero filler, with the core action front-loaded ahead of the constraint. Nothing could be removed without losing information.

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

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

For a mutation tool with no annotations, no output schema, and two undocumented parameters, the description is thin. It omits how to source istanza_id, the auth/role requirements behind the guarantor rule, vote reversibility, and error behavior for closed or already-voted instances.

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

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

Schema description coverage is 0% and both parameters are undocumented in the schema, so the description must compensate. It only indirectly implies that istanza_id must reference an open instance; it says nothing about the accepted vote values (though the enum is self-evident) or how to obtain a valid istanza_id.

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

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

The description pairs a specific verb ("Vota") with a specific resource ("un'istanza aperta"), so the agent knows this casts a vote on an existing motion. It is distinguishable from read siblings like leggi_istanze and from proponi_istanza, but it never names those siblings to draw the line explicitly, keeping it out of 5 territory.

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

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

"Un'istanza aperta" implies the precondition that the target instance must be open, and "un voto per garante, non per agente" constrains the caller. However, there is no explicit when-not guidance (e.g. what to do for closed instances) and no routing to alternatives such as leggi_istanze for inspecting instances before voting.

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