DeviL

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds useful beyond-annotation detail about the two operational modes and the shape of returned data (adherence level enum, top 5, ranking), though it omits pagination/limit considerations.

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 dense sentence using a colon-structured enumeration, front-loading the resource and then the two modes. Efficient, though slightly run-on with multiple clauses packed together.

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 must carry return-shape information, and it does so for both modes (companies with adherence and level; 5 easiest wins and ranking). Nothing critical is missing for a read-only query tool, though enum values are only loosely qualified.

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 100% and the single slug param is documented there, but the description adds real meaning beyond the schema by explaining the consequence of providing vs omitting slug. Baseline would be 3; the mode-switching semantics lift it.

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 resource (project–company matches) and precisely what is returned in each mode: companies with adherence/level for a given project, or the top 5 easiest wins plus a project ranking otherwise. It does not explicitly name a sibling, so it stops short of a 5, but the verb+resource is unambiguous.

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 branches on presence/absence of slug, effectively telling the agent when each behavior applies. It gives no explicit exclusions or pointers to alternative sibling tools, so it is strong context but not full when/when-not routing.

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 this is a non-read-only, non-destructive, non-idempotent mutation, so the safety profile is covered. The description adds genuinely new behavioral rules: credentials must be test-only and belong solely in demo_accesso, never in fatto, prossima_tappa or domanda, and the portal renders them as a table with a hidden password and copy button. It does not explain what happens on an invalid id or the effect of re-submitting the same update.

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?

Dense but well front-loaded: the core action and recorded fields come first, then the usage triggers, then the conditional demo-credential rules. Every sentence carries scenario or constraint information, though the paragraph is long enough that an agent must read it fully rather than skim.

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 12-parameter mutation tool with no output schema, the description covers the main workflows, the external-commit flag, and the credential-handling policy. It leaves minor gaps on error behavior and idempotency, and output/confirmation format is unspecified, but all required fields are documented in the schema at full 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 description coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining the conditional relationship between demo_url and demo_accesso based on where the demo is hosted. It also clarifies that demo_accesso is the single permitted location for credentials, which is semantic guidance the schema alone does not convey.

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 (aggiorna un cantiere di sviluppo) and enumerates exactly which fields it records (avanzamento, fatto, prossima tappa, cartella, ultimo commit, domanda). It also implicitly separates itself from the sibling pubblica_demo by noting that static demos go through that tool instead.

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?

Gives explicit trigger conditions: use at the end of each tappa, when closing a piece of work in a manual session, or to report commits made outside the portal (esterno: true). It also branches on the user's hosting choice, specifying demo_url + demo_accesso for 'Sul mio server' versus demo_accesso alone for 'Solo sul mio PC', and names pubblica_demo as the alternative for static demos.

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?

Adds substantial context beyond the annotations: asynchronous staged execution, one-search-per-organization concurrency limit, public-pages-only scraping, and additive behavior ('senza toccare quelle che hai già') consistent with destructiveHint=false. Also states return semantics ('le province avviate o il motivo per cui non è partita').

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?

Four sentences, front-loaded with the core action and constraint. Efficient with little waste, though the parenthetical '(sigle, max 8)' duplicates the schema.

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 an async job launcher with one param and no output schema, the description covers the async model, concurrency limit, non-destructive additive behavior, and what the call returns. An agent has enough to invoke it correctly and interpret the result.

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 100% and the description only restates schema facts ('sigle, max 8' matches the maxItems: 8 and the schema's own description). No additional format or semantic meaning is added, so baseline 3 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 ('Avvia la ricerca') and resource ('nuove aziende in una o più province') with scope (max 8). The staged/asynchronous framing ('Procede a tappe distanziate') distinguishes it from a plain lookup like cerca_aziende without opening either 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?

Gives a usage constraint ('una ricerca alla volta per organizzazione') but never names an alternative tool or an explicit when-to-use/when-not condition relative to siblings such as cerca_aziende or metti_in_coda. Usage is implied rather than routed.

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 idempotentHint=true and destructiveHint=false, and the description corroborates this by explaining the dedup keys (same P.IVA, website, or name+comune return the existing id). It also discloses a non-obvious side effect — supplying a website causes DeviL to scrape it and compute a score. No auth/permission details, but the added behavioral context is substantial.

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 with the core action front-loaded, followed by dedup and the site-scoring caveat. Each sentence carries information; no filler, though the phrasing is dense.

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 annotations covering safety and idempotency and a fully documented 11-param schema, the description covers the remaining gaps: return value on duplicates and the site-reading side effect. No output schema exists, and the description adequately explains what it returns.

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 100%, so the baseline is 3, but the description adds meaning beyond the schema by tying parameters to behavior: partita_iva is used for duplicate detection and sito triggers external reading and scoring. This parameter interaction is not apparent from the schema alone.

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 and resource ('Aggiunge un’azienda a mano') and clarifies the mode of entry versus automated sourcing. It doesn't explicitly name a sibling like cerca_aziende to differentiate, but an agent can still tell this is a manual create operation.

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?

It gives the usage context (a lead or trade-fair contact) and describes the duplicate-return behavior, which effectively signals when creation will be a no-op. However, it never tells the agent to look up first or names which sibling (e.g. cerca_aziende) to use instead when the company may already exist.

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 declare readOnlyHint=false and idempotentHint=false, and the description adds meaningful context beyond them: it 'takes at most one at a time' (explaining the non-read-only, non-idempotent nature), inspects git history per folder for unaligned commits, and can trigger an external call to aggiorna_cantiere (esterno: true). It still leaves the exact state effect ambiguous (whether the consumed cantiere is removed, marked, or merely read), which is the only real 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?

It is front-loaded with the tool's purpose before branching into the new / to-continue / active-alignment cases, which is the right ordering. The sentences are long and heavily embedded, but each one carries distinct information about a separate behavior, so little is wasted.

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 full burden of explaining returns and it does so concretely for each case (brief to save as CLAUDE.md, folder + user indications + next stage, unaligned commits). It is complete enough for an agent to act, though the side effect of consuming queue items and the relationship to sibling queue tools remain implicit.

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 of 4 applies. Nothing in the description needs to document inputs, and it correctly spends its text on outputs and behavior instead.

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+resource: it pulls queued development 'cantieri' from DeviL and returns either the brief (new) or folder/instructions/next stage (to continue). It is clear about what the tool does, but it never differentiates itself from similarly named siblings such as dossier_da_lavorare or metti_in_coda, leaving the agent to infer which queue-feeding tool is which.

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 through the two branches (new vs to-continue) and the mention of calling aggiorna_cantiere to report commits, which is a routing hint. However, there is no explicit statement of when to prefer this tool over siblings like dossier_da_lavorare, nor any when-not guidance or prerequisite conditions.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value annotations don't: it discloses the return shape (id, essential data, link to the detail page) and clarifies that the priority score is a list-ordering metric rather than a purchase probability, which heads off a common misreading of the punteggio_min filter.

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 sentences, front-loaded with the action and scope, followed by the return contract. The parenthetical filter list is dense but each item earns its place by previewing a real parameter; nothing is padded.

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 correctly compensates by stating what is returned, and all 9 optional parameters are covered by schema descriptions. The tool has no required params and a capped 'limite', so pagination behavior is covered; only the exact shape of 'dati essenziali' remains underspecified.

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 100%, so every one of the 9 parameters is already documented with descriptions and ranges. The description merely restates the filter categories (text, province, sector, min priority, distance, drafts, analyzed) without adding format or interaction detail beyond the schema, so baseline 3 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?

A precise verb ('cerca') plus resource ('aziende') scoped to the organization, with the filter set and the returned fields spelled out. It implicitly contrasts with create/detail siblings by noting it returns a link to the scheda, but it never names an alternative tool outright.

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 filter enumeration (search when you need to narrow companies by text, province, sector, priority, distance, draft state). There is no explicit when-to-use/when-not statement and no named alternative among siblings like panoramica or scheda_azienda.

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=false, idempotentHint=false, destructiveHint=false, so the agent knows this is a non-destructive but state-affecting call. The description adds real context (what the downloaded README contains, empty-queue outcome) but never says what the call mutates — i.e. whether the queue items are consumed/marked as taken — which matters given readOnlyHint=false and idempotentHint=false and would affect retry decisions.

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?

Front-loaded with the core action and the payload, then the workflow step, then the special-case parameter value. It is dense and a little run-on with nested parentheticals, but every clause (README contents, invia_risultati, top: 0, empty queue) carries information an agent needs.

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 tool with no output schema, the description covers the trigger, the follow-up tool, the top: 0 mode, and the empty-queue outcome. The only real gap is the side-effect/state semantics flagged above, which is not fully resolvable from the description alone.

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 100% and the single parameter already documents 'oltre alla coda, quante aziende migliori non ancora analizzate aggiungere (0 = solo la coda)'. The description restates the top > 0 case and adds the top: 0 operating scenario, which is marginal added meaning over the schema — the baseline 3 is appropriate.

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 (scarica) and resource (i dossier delle aziende in coda), plus the exact payload contents (README, regole di scrittura, catalogo, verifica date, ricerca in rete, formato risultati). It also positions itself in the workflow by naming the follow-up sibling invia_risultati, so an agent can separate this from the send step without opening either 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?

Explicit routing: use invia_risultati afterwards to send results, use top: 0 when only the queue should be worked (the /loop and 'Manda al mio Claude Code' cases are named concretely). It even covers the degenerate case — 'se la coda è vuota non c'è niente da fare' — which is exactly the kind of when-not guidance that prevents wasted calls.

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, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful context about the content (allowed values and an example) and sequencing advice, though it does not detail return format or whether the reference data is static.

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 that front-loads the resource and its contents, then closes with the actionable instruction. Every clause earns its place and there is no redundancy.

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 reference tool with no output schema and annotations covering safety, the description is nearly complete: it says what the tool contains and when to use it. A minor gap is that it does not explicitly state that it returns a static reference payload or in what format.

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 has zero parameters, so parameter semantics are not applicable and the baseline score of 4 applies. No parameter-related claims are made or needed in the description.

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 resource ('formato delle schede progetto') and explicitly lists what it contains: allowed values for sectors, software types, themes, and statuses, plus an example. It also distinguishes itself from the sibling tool 'portfolio_salva' by being the reference to read before saving.

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?

It gives an explicit condition for use: 'leggilo prima di portfolio_salva' (read it before portfolio_salva). This directly tells the agent when to invoke it relative to a named sibling, leaving no inference required.

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 write/no-destroy/non-idempotent behavior. The description adds real value beyond them: drafts in non-permitted channels are discarded and flagged, nothing is actually sent, the call consumes the monthly analysis quota, and a per-company summary is returned.

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 dense paragraph that front-loads the core action and format, then appends operational caveats and the return summary. No padding; every clause carries 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 a nested object parameter and no output schema, the description covers the side effects, the quota consumption, the draft-filtering rule and the return summary. It stops short of error/dependency conditions, but is largely sufficient.

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 100% and the single parameter is documented as a complete results.json object. The description goes further by spelling out the expected shape ({ "version": 1, "items": [...] }) and pointing to the README, adding format detail beyond the schema blurb.

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: it processes (saves and sends) analyses and drafts for one or more companies. Crucially it resolves the tension with its own name ('invia' = send) by clarifying that it saves without actually sending anything, so an agent knows the true effect.

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?

It gives context (the results.json format from the README, the treatment of drafts in non-permitted channels) but never states when to choose this tool over siblings like offerte_salva or portfolio_salva, nor prerequisites. Usage is implied rather than explained.

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 idempotentHint=true, destructiveHint=false and openWorldHint=false, but the description adds genuinely new behavior: no external contact is made, and re-queueing an existing company does not duplicate it. It also discloses the return value (the queued company name) despite there being no output schema.

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?

Four compact sentences, front-loaded with the action and immediately followed by where the result lands and the key constraint (no contact, no duplicates). Dense but essentially waste-free; only the colloquial 'Poi la trovi' could be trimmed.

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 3-parameter, non-destructive queueing tool with full schema coverage and annotations, the description covers purpose, side-effect boundary, idempotency and return value. Nothing essential to invoking it correctly 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 coverage is 100% and the `canale` enum already carries consent caveats, so the schema does the heavy lifting. The description only echoes that `canale` and `indicazioni` are optional and adds an example instruction, which is already mirrored by the schema's own example — marginal added value, so baseline 3 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 and resource ('Mette un'azienda in coda per Claude') plus the observable outcome ('Poi la trovi in dossier_da_lavorare'), which ties it to a sibling concept without ambiguity. The clause 'Non contatta nessuno: prepara solo il lavoro' separates it from outreach/result-sending siblings such as invia_risultati.

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 purpose and by the negative constraint that it only prepares work and does not contact anyone, which implicitly delimits it from sending tools. However, it never names an alternative or states the condition for choosing this over cantieri_da_lavorare or azienda_crea, so the agent must infer the routing.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds useful output context (per-offer company counts) but says nothing about pagination, ordering, or whether an empty result is possible.

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 no filler; the identity of the resource comes first and the usage rule second. Every clause carries 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 no-param, read-only list tool whose annotations already cover safety, the description tells the agent what it returns and when to call it. Only the absence of any return-shape or pagination note keeps it short of full completeness.

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 and the schema is empty, so there is nothing for the description to clarify beyond what it already does. Baseline 4 applies for a parameterless tool.

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 the resource precisely ("servizi, prodotti e cataloghi che l'organizzazione vende") and even characterizes the payload by noting each offer includes how many companies it fits. It also name-drops the sibling offerte_salva to draw the read/write boundary, though the verb is only implied via "Leggile".

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?

"Leggile prima di offerte_salva, per non duplicarle" gives an explicit precondition and the alternative that triggers it, which is more than most tools offer. It lacks any when-not-to-use case, but the workflow instruction is unambiguous.

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 cover the safety profile (readOnly=false, idempotent=false, destructive=false), so the bar is lower; the description still adds real value by disclosing a post-save side effect — DeviL computes matching companies after saving. It does not say whether the call returns the new id or how to retrieve the computed matches, but the annotation-plus-side-effect coverage is solid.

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, front-loaded with the create-or-update rule. The settori sentence ('le chiavi elencate nel campo settori') is slightly circular and redundant with the schema, which is the only real waste.

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?

No output schema exists, yet the key thing an agent needs to know about returns (that matches are computed asynchronously after saving) is stated. For a 1-required-param mutation tool with fully documented params and annotations, nothing critical 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 100% across all 11 parameters, so the baseline is 3. The description restates the id semantics (already in the schema) and gestures at settori/parole_chiave meaning, but adds no syntax, format, or constraint detail beyond 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+resource ('Crea o aggiorna un'offerta') and resolves the create-vs-update ambiguity inline via the id rule (id = update, no id = new). It does not, however, distinguish itself from siblings like portfolio_salva or offerte_elenco, which an agent must infer.

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 id/no-id rule gives a clear conditional for choosing create vs update, which is genuine usage guidance. But there is no guidance on when to use this tool versus portfolio_salva (the obvious sibling for saving a different entity) or when to read via offerte_elenco instead.

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 the full safety profile (readOnlyHint, idempotentHint, non-destructive, closed-world), so the description's job is lighter. It adds genuine value by disclosing the return contents — plan/limits, zone, counts, and 10 recommended moves — which is useful given there is no output schema.

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: the first front-loads what the overview contains, the second gives the routing cue. Every clause carries content, though the parenthetical enumeration of numbers is slightly dense.

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 and no parameters, the description must convey what comes back, and it does so by listing the overview's sections. For a simple read-only dashboard tool this is close to complete; only the exact format of the returned data is left 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies a no-argument, single-shot read with nothing for the agent to supply.

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 and resource — it reports the organization's situation on DeviL, enumerating plan/limits, zone, key numbers, and 10 recommended next moves. 'Usalo per primo' positions it as the entry-point dashboard, which meaningfully distinguishes it from the action-oriented siblings, though it doesn't name a specific alternative.

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?

'Usalo per primo' (use it first) gives explicit ordering guidance, telling the agent to call this before the other 16 tools. It provides a clear usage context but offers no when-not conditions or named alternatives, so it stops short of a 5.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior: drafts are included, and re-sending with the same slug becomes an update rather than a new record — the idempotency semantics in concrete terms.

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 that front-loads the resource and its scope (including drafts) before the usage rule and the slug/update behavior. Every clause earns its place with no padding.

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 no-parameter, read-only listing with no output schema and full annotation coverage, the description tells the agent what it returns (existing cards, drafts included) and how results relate to the save tool. It is complete enough to call correctly; only the exact return shape is left implicit, which is acceptable.

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 and there is nothing for the description to disambiguate. No parameter guidance is needed or missing.

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 resource (project cards already uploaded, including drafts) with the listing verb implied by 'elenco', and immediately frames it against the save action ('prima di inviarne di nuove'). An agent can tell this is the read/listing counterpart to portfolio_salva 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?

Explicitly says to read before sending new ones and gives the reason (avoid duplicates). This routes the agent to use this tool prior to portfolio_salva. It stops short of a named alternative or an explicit when-not-to-use case, so it is strong but not exhaustive.

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 idempotentHint, destructiveHint=false and readOnlyHint=false; the description adds genuinely new behavior: same-slug entries overwrite rather than duplicate, nothing is ever deleted, and it returns a count of saved sheets (useful since there is no output schema). It does not mention permissions or failure modes, so it is strong but not exhaustive.

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?

Four short sentences, front-loaded with the operation and limits, then format source, then content constraints, then return value. Every sentence carries information an agent needs.

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 non-destructive upsert with full annotation coverage, the description supplies the missing pieces: batch limit, format source, content rules, and the return count that stands in for the absent output schema. Only auth/permission expectations and error behavior are 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 coverage is 100% and the single parameter's description already explains the 1-50 range and same-slug update semantics. The description largely restates this and adds only the pointer to formato_schede, so the schema is doing the heavy lifting.

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 pair (inserisce/aggiorna) plus the resource (schede progetto), the keying mechanism (per slug) and the batch cap (fino a 50). This is clearly distinguishable from sibling portfolio_elenco, which only lists.

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?

Routes the agent to the sibling formato_schede for format and allowed values, and rules out a class of content ('solo fatti trovati nei file, niente segreti né codice'). It also clarifies the operation is an upsert, not a delete. It stops short of an explicit when-not-to-use statement, but the context is clear.

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 flag a non-readonly, non-idempotent, open-world write; the description goes well beyond them by disclosing the one-time 30-minute upload link, the required build layout, the zip + curl upload flow, and a pre-publish quality checklist. It also clarifies the consent gate, which is the main failure mode callers will hit.

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?

Purpose is front-loaded in the first clause, and the remaining sentences each carry distinct operational content (gating condition, return contract, build steps, quality check). It is dense and slightly run-on, but nothing is 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?

Although there is no output schema, the description spells out the return value (link monouso + istruzioni) and the full downstream procedure, and adds the quality-review requirement. Combined with one-parameter schema coverage, an agent has everything needed 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 coverage is 100% and the single id parameter is already documented as 'id del cantiere' in the schema. The description refers to the cantiere throughout but adds no new syntax, format, or sourcing detail for the id, so the baseline 3 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 and resource in one clause: mette online la demo statica di un cantiere sullo spazio demo di DeviL. The workflow context (destinazione DeviL, consenso, pulsante «Pubblica la demo») clearly separates it from the other *_salva and metti_in_coda siblings.

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?

Explicit preconditions are given (selezionato lo spazio DeviL, consenso, pulsante premuto) plus where to find the trigger (DEMO DA PUBBLICARE in cantieri_da_lavorare) and the fallback behaviour (altrimenti spiega cosa fare). This is exactly the when-to-use vs. when-not guidance an agent needs.

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 cover the safety profile (readOnly, idempotent, non-destructive, non-open-world), so the bar is lower. The description still adds useful behavioral context by disclosing the return format (Markdown) and the data sources it aggregates, including public registries (ANAC, archive.org) and site text, which tells the agent what to expect as output.

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 sentences, front-loaded with the noun-phrase identity of the tool followed by a dense but purposeful enumeration of contents and a usage clause. No filler, though the content list is long enough to slightly dilute the core 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 output schema, the description must describe the return value, and it does so thoroughly by listing the dossier's sections and noting the Markdown format. Combined with annotations covering the read-only nature, an agent has enough to call it correctly; only sibling differentiation is absent.

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?

There is a single parameter with 100% schema description coverage ('id dell'azienda (uuid)'), so the schema fully documents the input. The description adds no further syntax, format, or constraint detail about the id, making the baseline 3 correct.

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 exactly what the tool returns: a complete company dossier in Markdown, enumerated by content type (data, people, allowed channels, signals, ANAC/archive.org public data, content dates, site text). That is specific and imageable, though it never explicitly distinguishes itself from siblings like cerca_aziende or azienda_crea, which is why 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 closing clause 'Da leggere prima di analizzarla o scriverle' gives a clear when-to-use trigger: read before analyzing or writing to a company. It does not name a competing sibling or state any exclusion, so it is clear context without full alternative routing.

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