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

The description opens with 'Create a person alert subscription', a state-changing operation, while the annotations declare readOnlyHint=true. Per the stated rule, a write claimed against a read-only annotation is a direct contradiction; the description also adds nothing about delivery side effects, duplicate-subscription behavior, or auth requirements that would compensate.

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, zero filler: the action and monitored scope come first, the usage triggers second. The example event list is redundant with the schema but stays within a single clause and does not bury the takeaway.

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 and the input schema is fully described, so return values and parameter formats need not be explained here; the description covers purpose, scope and triggers adequately for a subscription tool. It falls short only on not clarifying the relationship to subscribe_insider_alerts and on the unresolved read-only/write discrepancy.

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 coverage is 100%, so person_id, event_types, delivery_method, email_address and min_transaction_value are all documented in the schema, and the description merely restates the event list already present there. It adds no semantics about how person_id and person_name interact or when delivery fields become mandatory, so the baseline 3 applies.

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 ('Create a person alert subscription') plus the scope it applies to ('monitor a specific individual'), and enumerates the monitored event categories. However, it never distinguishes itself from the overlapping sibling subscribe_insider_alerts, which shares the insider_trade event type, so an agent must infer the split from name 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?

Strong when-to-use clause: 'Use when a user wants to track or follow a person, set up alerts for a director or executive, or be notified about changes involving a specific individual.' It supplies concrete trigger scenarios but states no exclusions or alternatives (e.g., subscribe_insider_alerts for entity-level insider monitoring, list_alert_subscriptions to check existing subscriptions).

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