find-projects

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

Annotations already declare read-only, idempotent, non-destructive, so description doesn't need to repeat that. It adds valuable behavioral details: that archived projects can be deleted via delete-object, and that pagination is ignored in certain modes. However, it doesn't explicitly state that returns are read-only beyond annotations, but that's covered. Also, it notes that archivedStatus 'all' ignores pagination, which is useful. Minor gap: no mention of rate limits or auth, but not critical. A 4 is appropriate given the good annotation coverage and useful edge-case note.

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?

Description is concise, three sentences, front-loaded with main purpose. Each sentence adds new information: purpose and default, pagination behavior, and the isArchived field/deletion note. No fluff.

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 read-only list/search tool with rich schema (100% coverage) and output schema present, description covers all key aspects: default filtering, pagination behavior, wildcard search, and archived status handling. It even links to deletion, which is helpful. Given complexity, it is complete.

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%, and the description adds significant extra meaning beyond schema: it explains the interaction between archivedStatus and pagination, and clarifies that archivedStatus 'all' can be used to include archived projectsament. It also mentions isArchived field and deletion path, enriching parameter semantics beyond raw 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?

Clearly states it lists or searches projects by name, with a specific verb 'find' and resource 'projects', and differentiates from siblings like find-tasks and find-sections by focusing on projects. Also explains default active-only behavior, adding specific scope.

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?

Explicitly explains when to use it: to list all projects or search by name. Mentions default behavior (active only), when to use archivedStatus, and how pagination behaves in different modes. Names alternative deletion via delete-object for archived projects, providing usage context.

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