ghl_survey_get_submissions

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint, so the safety profile is clear. The description adds OAuth scopes and pagination behavior. However, it does not disclose that locationId is required or the filtering capabilities, which are important behavioral traits.

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 with three sentences, front-loading the purpose. It includes technical details like version header and file path that may not be essential but do not detract significantly. Structure is adequate for the length.

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?

With 7 parameters, 1 required, and no output schema, the description should cover filtering options (q, date range, surveyId) and the required locationId. It also lacks mention of the returned data structure. Annotations help, but the description is insufficient for a complete understanding.

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 high (86%), so the schema documents most parameters well. The description explains how page and limit are used for pagination, adding value beyond the schema. It does not describe other parameters like q, startAt, endAt, surveyId, or note that locationId is required.

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 it retrieves survey submissions. The keyword 'Get Surveys Submissions' effectively conveys the action, and the endpoint details reinforce the purpose. However, it does not explicitly distinguish from similar tools like ghl_survey_list, which lists surveys themselves.

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?

No guidance on when to use this tool versus alternatives, such as ghl_form_get_submissions or ghl_survey_list. The description mentions pagination but does not indicate prerequisites or scenarios where this tool is appropriate.

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