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

Annotations only assert read-only/idempotent/no-destructive, yet the description adds substantial behavior: the entitlement gating (first 5 rows in full, then locked.count/locked.by_type), that contact values and decision-maker names are never returned (only types and counts), that 'not on record' never means the sponsor needs one, and that total is the pre-limit count. This is far beyond what the structured fields disclose.

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 purpose and trigger definitions are front-loaded, but the whole thing is a single dense block mixing rule IDs, dates, trigger semantics, access rules and a marketing URL instead of breaking the trigger set into readable units. Almost every clause carries information, yet the unbroken wall and the closing plan pitch cost it structure points.

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 5-parameter, zero-required tool with no output schema and only 40% schema coverage, the description is remarkably complete: it describes the returned row contents, the ranking logic for the provider-scoped view, the count semantics, and exactly what is withheld under the free tier. An agent has everything needed to call it and interpret the response.

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 schema description coverage at 40%, the description compensates well: it defines each trigger enum value semantically (e.g., recent_deal_role_not_on_record = a deal in the last 180 days with no firm in this role on record), explains that provider accepts a dfx:isi: id or name and changes the shape of the result, and clarifies limit via the total-vs-limit distinction. `role_family` and `state` are only lightly enriched, keeping it off a 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 description names a specific artifact (the independent sponsor call list, rule isi-pcall-1) and spells out its row structure: one row per role family, trigger and sponsor over census-verified sponsor deals. It also covers the second mode (pass `provider` to get that firm's own ranked list). It never explicitly distinguishes itself from near siblings like who_to_contact, why_now or search_vc_provider_calls, so it stops 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?

Usage is implied rather than stated: 'Give provider ... to get that firm's own list' and the explanation of when each trigger fires tell the agent what the data means, but there is no explicit when-to-use-this-vs-alternative guidance or prerequisite (e.g., when to reach for this instead of who_to_contact or why_now). A capable agent can infer the fit, but the definition does not do the routing work.

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