get_new_document_defaults

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

readOnlyHint=true is consistent with a 'get' tool, so no contradiction. The description adds value by disclosing that the payload covers upcoming section numbers, defaults, VAT rates and templates — non-obvious return content for a no-output-schema tool — but says nothing about scope (per company? per document type?) or fallback behavior.

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 returned data front-loaded and the usage hint trailing, with no filler. It is dense but readable, though the compressed noun list ('sezionale, valori predefiniti, aliquote e modelli') is slightly opaque without domain familiarity.

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 2-param read-only tool with no output schema, an agent needs to know what comes back and how to use it; the description lists the payload categories and the pre-creation use case, which is adequate. It is still missing the link between the 'type' parameter and the returned defaults, which is the one thing that would make the call unambiguous.

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 only 50%, and the undocumented half is the important one: the 11-value 'type' enum has no description in the schema and the description never explains that the returned defaults vary by document type. 'Sezionale' and 'modelli' hint at document-type-dependent content but give no mapping, so the agent must guess how 'type' changes the result.

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 the resource loosely (next free numbers, defaults, rates, templates) but the verb is only implied by the tool name, not by the sentence itself. It is distinguishable from create_issued_document via the 'utile prima di creare un documento' clause, but the phrasing is a list of returned data rather than a crisp statement of what the tool does.

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?

'Utile prima di creare un documento' gives a clear triggering context, so an agent knows to call it in the pre-creation step. However, no alternative is named (e.g. whether a plain get_company_info or list_vat_types call would serve instead), and there are no exclusions or notes about whether the call is required.

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