humansurvey-mcp

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

With no annotations provided, the description carries full burden. It successfully discloses lifecycle behavior (accepts responses immediately, stays open until closed/expires) and return structure. However, it lacks safety disclosures (permissions required, validation behavior, idempotency, what happens on duplicate creation) expected for a resource-creating tool without annotation coverage.

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?

Five well-structured sentences that front-load use cases, specify input requirements, document return values, and explain lifecycle behavior. Each sentence earns its place by adding distinct information not redundant with structured fields, though the 'Use this when' opening is slightly less direct than an action verb.

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 lack of output schema, the description appropriately documents return values (survey_url, survey_id) and their purposes. It covers the complex nested input sufficiently by reference to 'JSON schema object' and explains integration points with siblings (get_results, close_survey). Minor gap: high-level webhook behavior isn't mentioned in description text (only in parameter schema).

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?

Input schema has 100% description coverage with detailed JSON schema specification. The description adds minimal semantics beyond the schema, primarily noting to 'Provide a JSON schema object' which partially overlaps with the schema parameter description. Baseline score of 3 appropriate given schema carries the detailed parameter documentation.

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 identifies the tool's purpose through use cases and return values (survey_url, survey_id), though it relies on the title for the explicit 'Create' verb using 'Use this when' construction instead of an action-first statement. It effectively distinguishes from sibling get_results by mentioning it as the destination for survey_id.

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 when-to-use guidance with concrete examples (post-event feedback, product satisfaction, team health checks). References sibling tool get_results in the workflow context (where to pass survey_id), establishing clear usage sequencing, though lacks explicit 'when not to use' exclusions.

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