List service providers

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds real value by disclosing the shape of the returned data (derived aggregates like task counts, visit frequency, and spend). It does not mention ordering, limits, or what an empty household returns, which is a minor gap for a zero-parameter read.

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 what the tool returns before the usage scenarios. The first sentence is a long comma-separated run, but every clause (contacts, counts, frequency, last visit, spend) describes a distinct useful output field, 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?

There is no output schema, and the description compensates by enumerating the returned fields. Combined with the explicit providerId dependency on add_maintenance/complete_maintenance and the duplicate-check role before add_provider, an agent has everything needed to call this 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?

The tool takes no parameters, so there is nothing for the description to disambiguate; baseline for a zero-param tool is 4. The description correctly spends no words on inputs and instead explains the output.

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 resource (the household's service providers) and enumerates exactly what the listing contains: contact details, task counts, visit frequency, last visit, and spend. An agent knows this is the provider roster, distinct from list_maintenance or list_items, 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?

Gives three concrete invocation triggers: answering 'who did we use for the furnace?', obtaining a providerId required by add_maintenance/complete_maintenance, and pre-checking before add_provider to avoid duplicates. It explicitly routes the agent to sibling tools and states the dependency relationship rather than leaving it to inference.

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