invite_usersInvites people to a site's app (up to 50 a call); each gets an invitation email. Naming someone who asked to join approves them (two steps). Returns invited, already and refused.
| Name | Required | Description | Default |
|---|---|---|---|
| plan | No | A plan id the invite is for | |
| site | Yes | ||
| emails | Yes | ||
| confirm_token | No |
| Name | Required | Description | Default |
|---|---|---|---|
| requests | No | ||
| approve_url | No | ||
| agent_message | No | ||
| confirm_token | No |
Changes observed during successful MCP inspections.
Output schema / properties / agent_messageAdded value: +{
+ "type": "string"
+}Output schema / properties / approve_urlAdded value: +{
+ "type": "string"
+}Output schema / properties / requestsAdded value: +{
+ "type": "number"
+}Output schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "confirm_token": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+}Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructive=true, non-idempotent, open-world. The description adds real behavioral context beyond them: a 50-recipient cap per call, that invitation emails are dispatched, that it can serve as approval for pending join requests, and the three result buckets returned. It does not mention permission/authorization requirements, which keeps it from 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?
Three compact clauses with the core action front-loaded and no filler; the 50-item cap and return buckets each earn their space. Slightly terse to the point of leaving key parameters unaddressed, but structurally sound.
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?
An output schema exists, so return-value detail is optional and the brief 'returns invited, already and refused' is a bonus. However, for a destructive, non-idempotent mutation with 4 params at 25% coverage, the missing explanation of site, emails, and especially confirm_token leaves an agent under-informed about correct invocation.
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 25%: site and emails are undocumented, and confirm_token — an unexplained, behaviorally significant parameter for a mutation — is never addressed in the description either. Only 'plan' is documented, and only in the schema. The description does not compensate for the coverage gap.
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 verb and resource (invite people to a site's app) and adds scope detail (up to 50 per call, invitation email sent). It does not differentiate itself from the close sibling add_people or email_users, which could plausibly overlap, so it falls short of a 5.
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 one usage-like statement — naming someone who asked to join approves them in two steps — is genuinely useful context about an alternate effect. But there is no explicit guidance on when to prefer this over add_people or email_users, and no prerequisites or exclusions stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.