getPuzzleProjectList

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

Annotations already mark this as read-only, so the safety profile is covered. The description adds useful behavioral context by documenting pagination via cursor/limit, status value semantics (0=upcoming, 1=ongoing, 2=ended), and optional filters by projectId or activityCoin.

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 main behavior is front-loaded in the first sentence, and the agent hint adds useful parameter details. There is some redundancy ('Use this endpoint to list Puzzle activities' repeats the first sentence), but overall the description remains concise and scannable.

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 endpoint with one required parameter and no output schema, the description provides enough to call it correctly: required status, optional filters, and pagination. It does not cover return shape or sort order, but those are less critical for a simple list operation and annotations already cover the read-only behavior.

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?

With 0% schema description coverage, the description must compensate, and it does for the most part: it explains status values, projectId as the project code, and cursor/limit for pagination. However, activityCoin is only restated as 'activity coin' and cursor mechanics are not detailed, leaving some ambiguity.

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 uses a specific verb and resource: 'Returns a paginated list of Puzzle activities filtered by status.' It clearly differentiates from nearby sibling tools like getLaunchpoolProjectList and getTokenSplashProjectList by naming the Puzzle domain and the filtering behavior.

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 explicitly says when to use this endpoint: to list Puzzle activities, browse them, or look up a specific project via projectId. It does not name alternatives or give when-not-to-use conditions, but the use case is clear enough for an agent.

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