humansurvey-mcp

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

No annotations are provided, so the description carries the full disclosure burden. It compensates by detailing the output content (status flags, response counts, statistical aggregations like mean/median/distribution, and text responses) and the polling behavior ('the output will tell you' if open). It lacks rate limits or caching notes, but covers the essential behavioral contract for a polling-based results 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?

Four sentences with zero redundancy: sentence 1 defines the retrieval action; sentence 2itemizes output fields; sentence 3 addresses polling logic; sentence 4 provides sibling routing guidance. Information density is high with no filler.

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?

Despite lacking an output schema, the description comprehensively enumerates return value structures (choice tallies with percentages, scale statistics, text responses). It adequately covers the operational context for a single-parameter read tool, though absence of error handling notes or annotation metadata prevents a perfect score.

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 100% schema description coverage for the single survey_id parameter (including format hints like 'last segment of the survey_url'), the schema fully documents semantics. The description adds no parameter-specific syntax or format details beyond what the schema provides, earning the baseline score of 3 for high-coverage schemas.

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 opens with 'Retrieve aggregated results for a survey'—specific verb (retrieve) + resource (aggregated results) + scope (survey). It explicitly distinguishes from the sibling close_survey by stating 'Use close_survey when you have enough responses,' clearly delineating this tool's read-only aggregation role versus the management role.

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?

Provides explicit temporal guidance ('If the survey is still open, call again later') and explicitly names the sibling alternative ('Use close_survey when you have enough responses'). This tells the agent exactly when to re-invoke versus when to switch tools.

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