Add a service provider

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

Annotations already declare write-but-not-destructive, non-open-world behavior, and the description usefully adds the one thing annotations cannot: it returns the new provider with its id, which matters since no output schema exists. Beyond that it says nothing about required vs optional fields, validation failures (e.g. malformed email), or whether duplicate names are rejected — with only 'name' required and seven optional fields, silence on which fields the tool will accept as empty is a 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?

Three short sentences, front-loaded with what the tool creates, followed by the dedup prerequisite and the return contract. Every clause earns its place; no restatement of the title or 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 an eight-parameter creation tool with no output schema, the description covers the missing piece — the returned id — along with the dedup check and where that id gets consumed. Combined with 100% schema coverage, an agent has enough to call it correctly without further probing.

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% with per-field examples already embedded ('Acme Heating & Air', 'Plumber', 'HVAC'), so the schema does the heavy lifting and baseline 3 applies. The description's 'with their trade and contact details' merely echoes the field set rather than adding format or constraint meaning, and it never notes that only name is mandatory.

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 ('Adds a service provider') and immediately grounds the abstraction with concrete examples (plumber, HVAC company, electrician) plus the fields it carries (trade, contact details). It also names its purpose in the wider workflow — so maintenance records can name who does the work — which distinguishes it from create_item or add_maintenance.

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 tells the agent to call list_providers first to avoid duplicates, then to reuse the returned id as providerId on add_maintenance or complete_maintenance. That is a complete when-to-use, prerequisite, and downstream-consumption chain, with the named alternatives rather than an inference.

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