Get Referencing Documents

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

Annotations already indicate idempotent, read-only, non-destructive behavior. The description adds valuable context: accepts entity by id or name (case-insensitive), ranked results, and empty return for unknown entities. No contradictions.

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, no redundant words, front-loaded with the primary purpose. Every sentence adds useful information.

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?

Given the simple parameter set and presence of an output schema, the description adequately covers purpose, input method, edge cases, and prerequisites. It omits ranking order details, but that is acceptable with an output schema.

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 sole parameter 'entity' has a schema description, but the tool description adds that it accepts both registry id and name (case-insensitive) and gives an example. This clarifies usage beyond the schema.

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 clearly states the verb 'find' and the resource 'documents that mention a given character or location', with ranking by mention count. It differentiates from siblings like 'find_mentions' by focusing on cross-document references.

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 description tells when to use: 'trace an entity's footprint across the manuscript'. It also specifies prerequisites ('Requires an open project') and edge cases ('Returns empty when nothing references it or the entity is unknown'). However, it does not explicitly state when not to use or mention alternative tools.

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