Add a person and app access

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

Annotations already declare destructive=true, idempotent=false, openWorld=true, so the bar is lower, yet the description adds real depth: newly scoped apps deny callers without a grant, TCP cannot be enforced, public Funnel is refused, invite needs a user-owned API token (OAuth cannot create device invites), print_links exposes bearer links, and there is no exactly-once guarantee. It loses a point for referencing behaviors like reconcile_invites and replace_invites without grounding them and for burying these facts in one undifferentiated block.

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?

After a reasonable first sentence, the remainder is a single dense run-on mixing access enforcement, invite mechanics, token auth, link exposure, resume semantics, login normalization, and replace_invites preconditions. It is front-loaded but not structured; an agent must parse a wall of text to extract the operational rules, and several clauses (reconcile_invites, 'retires its attempt') add noise for this tool.

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 9-parameter, destructive, non-idempotent tool with annotations and an output schema present, the description covers the important extras: confirmation requirement, auth constraints, enforcement limits (TCP, public Funnel), credential exposure, and partial-failure behavior. Return values are rightly left to the output schema. It is nearly complete, only weakened by the jumbled organization and ungrounded tool references.

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?

With 56% schema coverage across 9 params, the description meaningfully compensates: it explains invite (one gateway device invitation for routed apps, per-app invitations otherwise), print_links (reveals bearer links), and login normalization rules for who (trim outer ASCII whitespace, lowercase A-Z, exact-byte compare, invalid UTF-8 is a usage_error). The for/until/replace semantics are largely left to the schema, so it is not a full 5.

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?

The opening sentence gives a specific verb+resource: 'Changes local access to private HTTP and file apps for a person.' That is clear enough to act on, but the name/title say 'add' while the body also describes update/resume behavior, and no distinction is drawn against close siblings like people_grant, people_update, or people_remove. A competent agent can tell what it does, but not cleanly why it over the neighbors.

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?

It gives explicit pre-call directives ('confirm the person, apps and expiry with the user before calling', 'confirm before creating them') and routes one case elsewhere ('use the existing invite tools and their owner-configured elevated permission guard for those'). It also states the replace_invites precondition ('requires update with invite and no apps/for changes'). There is no explicit when-not-to-use versus people_grant/people_update, so it stops short of 5.

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