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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: one level of nesting via parentProjectId/path, and that counts are per project rather than rolled up — a detail that would otherwise cause wrong inferences.

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 sentences, front-loaded with the identity of the resource, then scope/contents, then the navigation hint. The quoted e.g. phrases earn their place by anchoring real user phrasings to this tool; no sentence is padding.

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?

With an output schema present, return values need not be explained, and annotations cover safety; the description nonetheless fills the important gaps (nesting depth, per-project counts, next-step routing). The one residual gap is guidance on the sort parameter's three modes, which neither schema nor description explains.

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 only 50%: limit and cursor are documented in the schema, but sort and query carry no schema description. The description compensates for query ("find a project by name") and implies paging via the projectId follow-on flow, but adds nothing about sort's recent/oldest/name enum or how limit interacts with paging. Partial compensation, so borderline.

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 ("Lists the user's Kalima projects") and immediately disambiguates what a project is ("folders that group recordings") and its scope (own and shared). The example phrasings plus the note on nesting and non-rolled-up counts let an agent distinguish this from get_project and list_recordings 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?

Offers clear routing: "Use query to find a project by name, then pass its projectId to list_recordings or get_project," which names the follow-on siblings explicitly. It stops short of stating when not to call this (e.g. when you already hold a projectId and should call get_project directly), so it is clear context rather than full when/when-not coverage.

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