find-labels

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by detailing the pagination behavior, search handling (ignoring limit/cursor), and the distinction between personal and shared label metadata. It also discloses that shared labels lack IDs and metadata, which is crucial for downstream usage.

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 well-structured, starting with the general purpose, then explaining the two types of labels, and then the two behavioral modes. It is dense but clear, with no fluff or redundant phrases, and every sentence adds distinct 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 tool's moderate complexity (two label types, pagination, search behavior), the description covers all major aspects: what is returned, how pagination works, how search affects results, and the metadata difference. Combined with the rich annotations, it is complete for an agent to use correctly.

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 the parameters well (100% coverage), so the description adds context beyond the schema by explaining how they interact: limit/cursor are ignored during search, and searchText supports wildcards. That said, it doesn't add unique high-value info beyond what the schema already describes, but it does contextualize usage.

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 what the tool lists labels, distinguishing personal labels vs shared labels, making the purpose is clear and distinct from siblings like find-labels' siblings like find-tasks or find-projects. It specifies the resource (labels) and the action (list/search) with precision.

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 explicitly explains when to use the tool (listing labels, searching by name) and contrasts with alternatives implicitly: by noting shared labels are returned as names only. The description even notes the difference in behavior when searching vs not, guiding the agent on parameter usage.

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