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

Beyond the readOnlyHint and destructiveHint annotations, the description adds crucial behavior: asynchronous indexing means recent edits may not be searchable, and empty results are not proof of absence. It also discloses cursor-based pagination. No contradiction with annotations.

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 with no fluff. Purpose is front-loaded, the pagination note is briefly stated, and the indexing caveat is essential yet concise. Every sentence adds value.

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 an output schema present, the return format is already covered, and the description adds operational details like pagination and indexing lag. However, it omits explanation of limit and category parameters, which are not described in the schema. This gap makes the definition adequate but not fully complete for an agent deciding how to scope a search.

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 schema covers query and cursor with descriptions (50% coverage). The description mentions cursor-based pagination, which adds context, but it does not explain the limit bounds or the category enum meanings. The description only partially compensates for the missing schema descriptions of limit and category.

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 it searches Lightbringer organisation documents (inventions, patent applications, reports) and specifies the return fields (ID, title, summary). This is a specific verb+resource scope that distinguishes it from sibling tools like get_invention (direct fetch) and list_inventions (enumeration).

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 implies usage for content-based search but does not explicitly explain when to use it versus alternatives (e.g., 'use get_invention when you know the ID'). There are no when-not-to-use instructions or alternative routing, so the guidance remains implicit.

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