monica_contacts

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

Annotations flag destructiveHint=true broadly, and the description sharpens that by scoping destruction to the delete action and stating it removes 'everything attached to it'. It also discloses non-obvious update semantics ('fields left out are kept, null clears one') and error behavior when a name is ambiguous. No permission or rate-limit context, which keeps it short of a 5.

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-loads the resource, then one bullet per action, each starting with the verb. Dense but zero filler, and the cross-cutting name-or-id rule is placed last as a global note rather than repeated per action.

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 22-parameter, six-action tool with no output schema and sparse schema descriptions, the description covers action selection, the destructive path, and update semantics well. It stops short of mapping parameters to actions or describing the shape of list/search results, but those are secondary given the actions are already disambiguated.

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 only 9% across 22 parameters, so the description must carry the load. It does clarify that only first_name is required for create, that confirm gates delete, that include extends get, and that a name substitutes for an id — but the bulk of profile fields (job, gender, company, birthdate, first_met, deceased, etc.) and the list controls (page, limit, sort) remain undocumented.

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 ('People in Monica, the personal CRM') and then enumerates six distinct verbs — search, list, get, create, update, delete — each with its own scope. An agent can tell contacts apart from monica_notes, monica_activities and the other siblings from the description alone.

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 routing for the primary entry point ('search — ... Start here when a person is mentioned') and states the precondition for the dangerous action ('delete ... confirm: true'). It does not, however, explain when to prefer this tool over overlapping siblings such as monica_contact_info or monica_relationships, so no exclusion guidance.

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