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

Annotations already declare readOnlyHint=true, and 'GET /logs' reinforces that this is a safe read. The description adds useful context about what each entry contains, but says nothing about pagination behavior, retention windows, max date-range spans, or rate limits that matter for a paged audit endpoint.

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 short clauses: purpose, disambiguating question, and endpoint confirmation. Front-loaded with the core verb+resource, and no sentence is wasted.

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 six-parameter paged list with no output schema, the description does convey entry contents and a targeting use case, which partly compensates for the missing return-shape detail. It still omits pagination semantics and how the entity filters interact, leaving the agent to infer endpoint behavior.

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 100%, so all six parameters (page, size, date bounds, entity_id, entity_type) are already documented. The description adds no filtering syntax or format detail beyond the schema, so the baseline 3 is appropriate.

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 (list audit-log entries) plus the fields returned (who/what/entity/when), which is far more informative than the title alone. It implicitly distinguishes itself from sibling getters since it is the only logs tool, but it never names a sibling or contrasts scope explicitly.

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?

The line 'The tool for answering \'who touched this token?\'' gives an implied use case, which nudges an agent toward audit queries. However there is no explicit when-to-use vs when-not guidance, no mention of the sibling basis_theory_list_log_entity_types that pairs with the entity_type filter, and no prerequisites.

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