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

The annotations only indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds rich behavioral context: IBANs are registered only as 'in attesa di conferma', never as confirmed, with the rationale that an IBAN on a document is not a baseline. It also discloses that excluded items (full plan, already watched, missing identity) are returned counted and motivated, and that it requires an API key but consumes no credits. This significantly goes beyond the annotations.

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?

The description is concise and front-loaded. The first sentence has the main verb and purpose, subsequent sentences add essential details (IBAN policy, exclusion handling, API key, credits) without redundancy. Every sentence contributes meaning, and the structure is easy to scan.

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 write tool with a complex nested schema and no output schema, the description is fairly complete. It explains what happens to excluded suppliers ('viene restituito contato e motivato'), the authentication requirement, and the non-consumption of credits. It could be more explicit about the exact response shape or common error cases, but the provided context is sufficient for an agent to understand the operation's scope.

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 schema already provides 100% description coverage, including details like iban entering as 'in attesa di conferma' and expected_country's purpose. The tool description reinforces these with the principle 'MAI come confermati' and explains the exclusion outcome for incomplete identities, adding context about how the system treats the supplier parameters. This adds value beyond the schema, though the schema already does 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?

The description clearly states the verb and resource: 'Registra uno o piu' fornitori nel guardiano' (registers one or more suppliers in the guardian) and explains the purpose: so that IBAN changes and VIES variations are intercepted by nightly checks. It distinguishes from sibling tools like 'guardian_check_iban' (which checks IBANs) and 'guardian_list_suppliers' (which lists suppliers), making it uniquely about adding suppliers to surveillance.

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 implies when to use: when you want to start monitoring suppliers for IBAN/VIES changes. It provides context such as the API key requirement and the fact that IBANs are only marked as 'pending confirmation'. However, it does not explicitly name alternatives or state when not to use, but the sibling tools make the use cases obvious. This is clear context without explicit exclusions.

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