create_contact

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

No annotations are supplied, so the description carries the full behavioral burden. It does add one genuinely useful fact — the contact lands in the default account, usually iCloud — but says nothing about duplicate handling, required permissions/consent, or what happens when Contacts.app is unavailable or the account is not iCloud.

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 single sentence is truncated mid-word, leaving an incomplete clause and a dangling field list. What is present is front-loaded and efficient, but the text is unusable as written.

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?

With no annotations, no output schema, and a truncated description, an agent cannot tell what inputs to supply or what a successful call returns. The account-location hint is the only substantive detail, and it does not cover the gaps for a create/mutation operation.

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 declares zero properties, so by baseline this would be a 4, but the description begins enumerating inputs ('name, c...') that do not exist in the schema, creating ambiguity about whether the tool takes any input at all. The truncation prevents the enumeration from clarifying anything.

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 ('Creates a contact') and pins the target system as the Mac's Contacts.app in its default account, which usefully separates it from the m365_/outlook_ contact siblings. The sentence is cut off mid-word, so the scope statement is clear but the remainder is unreadable.

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?

No when-to-use or when-not-to-use guidance. Given siblings like m365_create_contact, outlook_get_contact and create_contact_group, an agent must infer from the platform name alone whether this is the right tool. No prerequisites or exclusions are stated.

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