What each share link was used for

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

With no annotations, the description carries the full disclosure burden. It does well: it states owner-only access, read-only semantics, defines key computed fields (visits, returned, first/last seen), and explains the events flag behavior. It does not mention pagination or error cases, which prevents a perfect score.

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 description is dense but every sentence earns its place: owner restriction, endpoint, output fields with definitions, the L5 signal, and the events flag. Parenthetical definitions keep it structured and scannable.

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 read-only analytics tool with no output schema and no annotations, the description covers return fields, field definitions, owner restrictions, and the optional events behavior. It is nearly complete, but missing explicit scan_id semantics and default/error behavior leaves a small but real gap.

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?

The description explains the events parameter ('events:true appends the raw event list') and clarifies the access_id output concept. However, the required scan_id parameter is never explained, and the schema has zero property descriptions, so a critical parameter's semantics are left to inference.

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 is specific: it names the resource ('share-link access log'), the endpoint ('GET /share/access'), and the exact operation ('Owner-only read'). It clearly differentiates this analytics tool from siblings like scene_share by focusing on per-link usage behavior rather than sharing or scene measurement.

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?

It gives a concrete use case: this is the behavioural evidence for customer discovery, with the important L5=returned signal explicitly defined. It also tells the agent to match access_id to the person the link was sent to. It does not explicitly mention alternatives or exclusions, so it falls just short of a 5.

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