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

Annotations only declare it as non-read-only, non-idempotent, and non-destructive; the description adds substantial context beyond that, including the hard 60-event cap, exact case-sensitive naming, and a real side effect ('each event's description and property descriptions are also copied into the event list where the event has none yet'). It also explains the post-save lifecycle (Gamebeast tracks events from planned to verified as data arrives), which helps the agent set expectations. It stops short of describing what the call returns or failure behavior, keeping it just under 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?

The core action is front-loaded in the first sentence, with prerequisites and constraints following in priority order. Four sentences are all relevant, though the clause about descriptions being copied to the event list is embedded mid-paragraph and could be separated for scanability. No filler or marketing language.

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 nested, mutating creation tool with no output schema and 83% schema coverage, the description covers prerequisites, limits, side effects, and lifecycle well enough to call correctly. The main remaining gap is that it doesn't tell the agent what happens on success (e.g., an id or plan reference returned), which matters slightly for chaining into update_tracking_plan_items, but that is mitigated by the named follow-up tools.

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 already 83%, so the schema carries most parameter meaning (title, reason, projectId, environment, nested event fields). The description reinforces a few semantics, notably that reason is user-facing ('Saved when this runs; explain it in reason') and the 60-item cap, but these largely repeat schema constraints rather than adding new meaning. Baseline 3 is appropriate given the high coverage.

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 description opens with a specific verb and resource ('Save a tracking plan') and immediately enumerates the payload content: events ('marker types') with when they fire, why they matter, placement, and typed properties. It distinguishes itself from update_tracking_plan_items and get_tracking_plan by naming them as downstream/companion tools rather than alternatives, so an agent can identify the create path without opening the schema.

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?

Explicit preconditions and routing are given: 'Check list_event_types and get_tracking_plan first: continue an open plan rather than starting another, and don't plan events the SDK already sends by default.' It also mandates loading the manage-events skill first, which is a concrete when-to-use gate. Exclusion guidance (no default SDK events, no duplicate plans) is stated directly rather than inferred.

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