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

Goes well beyond the annotations (which already cover readOnly/idempotent/non-destructive) by disclosing the required mention:read scope, the account-connection requirement, the exact recovery flow on AUTHENTICATION_REQUIRED, pagination bounds of 1-100, and the shape of returned rows. It also adds a substantive interpretation caveat that results are detections, not proof of infringement.

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?

Front-loaded with purpose, then usage, then return shape, then auth — a sensible order in a compact paragraph. Slight redundancy in the trailing bracketed tag ('Needs a connected WEIR AI account; scope mention:read') which repeats the auth/scope facts already stated in the body.

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 no output schema, the description carries the return-value burden and does so by enumerating source link, date, type and status plus suitability for a table. Auth, scope and pagination are covered; only edge behaviors (empty results, out-of-range pages, ordering) are left implicit.

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 33% (only external_id documented), so the description must compensate: it explains where external_id comes from and the page/per_page bounds, exceeding the schema's bare minimum/defaults. Minor friction: it points to get_public_license while the schema points to list_licenses, and paging semantics (beyond the numeric bounds) are not explained.

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?

Specific verb+resource: 'Retrieve detected mentions for a license' with an authorization scope qualifier, plus a caveat that 'Detection is not proof of infringement.' It does not, however, distinguish itself from the sibling search_mentions, so an agent must infer the difference.

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?

Gives concrete operational guidance: use the external_id already named in the conversation (e.g. from get_public_license) rather than asking the user to repeat it, and describes the AUTHENTICATION_REQUIRED recovery path with a single retry. It stops short of stating when to prefer search_mentions over this tool.

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