search_projects

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

With no annotations provided, the description carries the burden of behavioral disclosure. It explains pagination and the returned fields (project alias, title, owner), and clearly states the public-only limitation. It stops short of detailing search semantics (e.g., case sensitivity, partial matching) but is sufficiently transparent for a simple search tool.

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 two sentences and front-loaded with the primary purpose. Every sentence contributes essential information: the action/scope, the result shape, and the key limitation with alternative. No fluff or redundancy.

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?

Without an output schema, the description gives a useful preview of the return contents ('project alias, title, and owner') and pagination, which is essential for an agent. It lacks explicit mention of the overall response envelope (e.g., total count, next page token), but for a search tool of this simplicity, the information is sufficient for correct invocation and basic expectation setting.

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 already documents all three parameters with descriptions, achieving 100% coverage. The tool description adds minimal parameter-specific detail beyond noting the search is by title and that results are paginated, which is reflected in the schema. Thus, the description provides no significant additional value over 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 a specific action ('Search for public projects across all of GitFlic by title') with a defined scope. It also distinguishes from closely related sibling tools by explicitly noting that private projects are handled by list_projects.

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?

Explicit guidance is provided: 'Only finds public projects — use list_projects for your own private projects.' This tells when to use this tool and directs the user to an alternative for the excluded case.

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