get_votes

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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals pagination behavior, cursor handling, and date constraints. However, it does not describe the return structure beyond the cursor, nor does it mention rate limits, authentication requirements, or error handling. The description is partially transparent but lacks some critical behavioral details.

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 concise, consisting of three sentences that front-load the main purpose followed by essential usage details. Every sentence adds value, and there is no unnecessary 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 absence of an output schema, the description should explain what the tool returns. It mentions the cursor and null cursor meaning, but does not describe the actual vote data fields (e.g., user, timestamp). Additionally, it lacks information on error cases or rate limits, leaving gaps for a complete understanding of the tool's 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?

The input schema has 100% coverage, but the description adds significant value beyond the schema by explaining the usage flow: startDate for the first page, cursor for subsequent pages, mutual exclusivity, and the condition for the project parameter. This additional context is crucial for correct invocation.

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 that the tool fetches a page of vote history for the current Top.gg project, specifying the verb 'fetch' and the resource 'vote history'. However, it does not explicitly differentiate from sibling tools like check_user_vote, which might also deal with votes.

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 provides explicit guidance on how to use the tool: use startDate for the first page, cursor for subsequent pages, and notes that a null cursor indicates no more pages. It also states constraints like startDate max 1 year ago and mutual exclusivity of cursor and startDate. However, it does not mention when not to use this tool versus alternatives.

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