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

Goes well beyond the readOnly/idempotent annotations by enumerating what comes back (matched-item count, ranked projects, sections, subjects, people, countries, formats, sample items, the seed's amira_url), disclosing the `matching` echo field, and warning that `matched_items` counts ITEMS rather than headings. With no output schema, this disclosure is exactly the burden the description must carry.

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?

A dense but well-ordered paragraph: purpose first, then return contents, then the matching/count caveats. Every clause carries information, though the return-value enumeration makes it longer than strictly necessary for a single-sentence read.

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 three-parameter discovery tool with no output schema, the description covers inputs, traversal semantics, and the shape of the response, including the subtle counting distinction an agent would otherwise get wrong. Nothing material is missing.

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 100%, so the baseline is 3; the description adds value by tying entity_type values to behavior ('subject and person seeds also pivot into the cluster bibliography', 'tags are merged into subjects — there is no tag pivot'). It does not add further syntax detail for value or limit.

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 ('given one entity, find what it connects to through the research items that mention it') and names the traversal mechanism (cross-entity discovery via co-occurrence). It also distinguishes itself from the closest sibling by contrasting its item count with list_subjects' heading count.

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 use cases in the user's own phrasing ('what subjects/people/places co-occur with X?') and a second scenario (tracing a theme across projects), plus an explicit contrast with list_subjects. It stops short of stating when NOT to use it or naming a full alternative for other query shapes.

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