Gitopia MCP Server

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

No annotations provided, but description compensates by disclosing return fields ('Returns id, title, summary...executor_result'). Missing explicit read-only safety declaration or error behaviors, but implies non-destructive read operation through 'get' naming and return value documentation.

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?

Four efficient sentences: use case, return values, requirements, and cross-references. Every clause earns its place. Information is front-loaded with conditional trigger ('Use this when...'), followed by concrete outputs and dependencies.

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 single-parameter retrieval tool without output schema, the description is complete. It documents all return fields compensating for missing output_schema, specifies the sole required parameter, and contextualizes within the DAO workflow via sibling references.

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 coverage is 100% ('The unique ID of the proposal'), establishing baseline 3. Description reinforces requirement ('Requires proposal_id') but adds no additional semantic context (e.g., where to find proposal IDs) beyond schema specification.

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?

States specific purpose ('full details about a specific DAO governance proposal, including tally results') with clear resource identification. Distinguishes from sibling tools by emphasizing 'specific' proposal retrieval vs listing (dao_list_proposals) or actions (dao_vote, dao_exec).

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 defines when to use ('when you need full details') and provides direct cross-references to alternatives ('See also: dao_list_proposals, dao_vote, dao_exec'), creating clear decision boundaries between retrieval and action tools.

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