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

With no annotations, the description carries full burden. It discloses that the tool initiates a checkout flow, requires user browser interaction, and credits are added asynchronously. It does not mention rate limits, auth needs, or failure scenarios, but overall provides sufficient behavioral context.

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?

Very concise: three sentences plus Args line. Front-loaded with main action. Clear structure with separate paragraph for return behavior and parameter.

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 simple tool with one optional param and an output schema (hosted checkout URL), the description covers the essential purpose and flow. It doesn't mention prerequisites or server configuration defaults, but overall complete enough.

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 description coverage is 0%, but the description explains the only parameter product_id: optional, omit for default bundle. This adds meaning beyond the schema's 'Product Id' title. However, it could provide more detail on product_id format or validation.

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?

Clearly states the tool opens a checkout link to purchase credits, and specifies it returns a hosted URL. This differentiates it from all sibling tools, none of which involve purchasing credits.

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 describes when to use: to purchase Datapoint AI credits. Explains the flow (user completes payment in browser, credits land after confirmation). No explicit when-not or alternatives, but given sibling set, it's clear this is the only credit purchase tool.

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

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

No annotations provided, but description fully covers irreversibility, in-flight response completion, credit return vs non-refund, and error conditions.

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?

Well-structured with header, warning bullet, usage advice, error note, and parameter description. Concise without missing critical 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?

Covers all necessary behavioral aspects for a destructive operation. Output schema exists, so return values are not required in description.

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 description coverage is 0%, but description includes an 'Args' section that explains job_id as 'The job ID returned by create_survey.' Adds meaning beyond schema, though still brief.

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?

Clearly states the tool cancels a survey permanently and settles reserved credits. Distinguishes from pause_survey, which is listed as a sibling tool.

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 advises to confirm with user before calling and prefers pause_survey for temporary stops. Also notes backend error for terminal states.

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

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

With no annotations, the description carries full burden for behavioral disclosure. It only says 'check', implying read-only, but lacks details on side effects, latency, permissions, or output structure (though an output schema exists). The description is insufficient for an agent to understand behavioral traits beyond the basic verb.

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?

A single sentence that is direct and front-loaded, with no extraneous words. Every word serves a purpose, achieving maximum conciseness.

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 simple read-only balance check tool with no parameters and an output schema, the description is adequate but minimal. It does not mention the return format or confirm it is a safe operation, which could be beneficial for an agent to fully understand the tool's context.

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 tool has zero parameters, so per guidelines baseline is 4. The description adds no param-specific meaning, but none is needed as the schema covers all (empty).

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 the action ('check') and the resource ('your Datapoint AI account balance'), leaving no ambiguity. It effectively distinguishes from sibling tools like 'add_credits' or 'create_survey' which serve different purposes.

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 explicit guidance on when to use this tool versus alternatives. While the purpose is straightforward, the description does not explain how it differs from similar operations (e.g., checking balance via another method), missing an opportunity to prevent mis-selection.

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

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

No annotations are provided, so the description must disclose behavioral traits. It only states the tool checks status, progress, and results, which implies read-only but does not explicitly confirm no side effects or destructive actions.

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 (two sentences) and front-loaded with the purpose. It avoids unnecessary words, though the parameter description could be integrated more naturally.

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 simple single-parameter tool with an output schema, the description covers the essential purpose and parameter. The existence of an output schema means return values need not be detailed.

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 0% description coverage, but the description adds the meaning of 'job_id': 'The job ID returned by create_survey.' This clarifies the parameter's origin and role beyond the schema.

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 the tool checks 'status, progress, and results' of a survey. The verb 'check' and resource 'survey' are specific. Sibling tools like create_survey, cancel_survey, etc., are distinct operations.

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 mentions that job_id is returned by create_survey, implying usage after creation. However, there is no explicit guidance on when not to use it or alternatives.

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

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

With no annotations provided, the description fully discloses behavior: immediate credit reservation, no draft/staging, irreversibility, human annotation dispatching, chain plan task linking, and media validation rules (dp:// references or public HTTPS URLs). This is comprehensive beyond what annotations would typically cover.

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?

Despite being long, the description is well-structured and front-loaded: the core purpose and critical warning appear first, followed by media validation and parameter details. Every sentence adds necessary information for correct usage, and the bullet-style media notes improve readability.

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?

The description thoroughly covers input semantics and behavioral caveats, but does not mention the tool's return value or output structure. Given that an output schema exists (as per context signals), this gap is mitigated, but a brief note on what the tool returns would improve completeness.

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 only defines 'plan' as an object with no description (0% coverage). The description compensates fully by explaining the plan structure (name, summary, datapoints, task_type/instruction or steps), how to edit it, media organization (shared vs per-step), and providing concrete examples of fixing references.

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 creates a survey from a plan generated by plan_survey. It uses specific verbs and resources, and the purpose is immediately distinguishable from sibling tools like plan_survey (planning) and cancel_survey (cancellation).

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 when-to-use guidance: only after user confirms the plan summary and cost from plan_survey. It warns about credit reservation and irreversibility, gives examples of editing the plan dict, and clarifies media requirements. It also explains chain plan usage, making it clear when and how to use this tool.

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

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

With no annotations provided, the description carries the full burden. It explains default filtering behavior, the effect of include flags, and implies read-only operation. However, it does not explicitly state that the tool is read-only or describe any authentication requirements or rate limits, leaving minor gaps.

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 well-structured with a concise summary, contextual paragraph, and bulleted Args. Every sentence is informative with no redundancy. The front-loaded purpose ensures quick understanding. It is appropriately sized for the tool's complexity.

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 presence of an output schema (removing the need to describe return values), the description fully covers all aspects: purpose, usage context, parameter details, and behavioral nuances. It is complete for a tool with 5 parameters and no nested objects.

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 0%, so the description must compensate fully. It provides clear descriptions for all 5 parameters in an 'Args' section, including defaults, constraints (max 200), and behavioral implications for boolean flags. This adds significant value over the bare schema.

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 states 'Get the raw per-annotator responses for a survey' with a specific verb and resource, and explicitly contrasts with the sibling tool 'check_survey' which returns aggregated results. This clearly distinguishes the tool's purpose.

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 when-to-use guidance: 'Use this tool when you want to see individual responses from each annotator' and lists use cases. It also differentiates from check_survey and explains the default exclusion of abandoned/in-progress responses.

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

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

No annotations are provided, so the description must convey behavioral traits. It states the action (listing) but does not disclose any constraints, such as whether results are paginated, ordered, or filtered by user scope. The phrase 'your surveys' implies user-specific, but details are missing.

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 a single, clear sentence that efficiently conveys the tool's purpose. No extraneous words. It is appropriately sized for a simple, parameterless tool.

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 tool's simplicity (no parameters, no complex behavior) and the presence of an output schema, the description is mostly complete. However, it could mention that the list includes both active and recent surveys, which is done. Missing subtle context: what constitutes 'recent'? Still, for a listing tool, 4 is justified.

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 tool has no parameters, so schema coverage is 100%. The description does not add anything beyond the schema truth, but since there are no parameters, a baseline score of 3 is appropriate.

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 'List all your surveys (active and recent)' clearly states the tool's purpose: listing surveys, with a specific scope (active and recent). It uses a specific verb ('List') and resource ('surveys'), and distinguishes itself from sibling tools like 'check_survey' or 'plan_survey' by focusing on listing rather than individual inspection or creation.

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?

There is no guidance on when to use this tool versus alternatives. For example, no mention of when to use 'list_surveys' over 'check_survey' or 'plan_survey'. The description assumes the agent knows the context, but fails to clarify boundaries.

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

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

Discloses that in-flight responses continue, new tasks stop, and errors occur for inactive surveys. No annotations present, but it covers key behaviors. Could mention reversibility via resume_survey.

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?

Concise and well-structured: first line states purpose, then explains behavior and errors. Every sentence adds value.

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?

Covers essential aspects for a simple tool: purpose, side effects, error conditions, and parameter source. Lacks prerequisites or permissions, but output schema exists and is separate.

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?

Job_id parameter is explained as 'The job ID returned by create_survey', which adds meaning beyond the schema. Despite 0% schema coverage, the description compensates adequately.

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 the tool pauses task serving for an active survey, differentiating it from siblings like resume_survey and cancel_survey. It specifies that in-flight responses continue while new tasks stop.

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 clear context on when to use (to pause an active survey) and warns of 400 errors for invalid states. However, lacks explicit alternatives or when-not-to-use guidance beyond error conditions.

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

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

No annotations provided; description carries full burden. It discloses that create_survey spends money, that media refs are needed to avoid failures, and that results include a cost summary. Lacks explicit read/write hint but overall informative.

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?

Well-organized with sections and example. Slightly verbose but each part serves a purpose. Front-loaded with main intent.

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?

Covers all necessary workflow aspects: planning, media handling, user confirmation, cost responsibility. Output schema exists, so return values need not be explained.

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 0%, but description explains both parameters in detail: description includes audience, criteria, media refs; max_responses covers default value and cost trade-off. Adds substantial meaning beyond schema.

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 'Plan a survey from a natural language description', specifying the verb 'Plan' and the resource 'survey'. It distinguishes from sibling tools like create_survey by emphasizing that planning precedes creation.

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 tells the agent to use this tool before create_survey, wait for user confirmation, and never chain the calls. Provides specific guidance for media surveys and references upload_media as an alternative step.

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

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

No annotations provided, so description carries full burden. Mentions rejection condition but does not detail other behavioral traits like what resuming entails or any side effects.

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?

Three concise sentences with no redundancy. Front-loaded with purpose, then condition, then parameter explanation.

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 simple nature of the tool and presence of output schema, the description provides necessary context: purpose, precondition, and parameter. No missing critical information.

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?

Explains the parameter 'job_id' as 'The job ID returned by create_survey', adding origin context beyond the schema's simple 'Job Id' label. Schema coverage is 0% but description compensates well.

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?

Clearly states 'Resume task serving for a paused survey', which is a specific verb+resource action. Distinguishes from sibling tools like pause_survey and cancel_survey.

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?

Specifies that the backend rejects with 400 if the survey is not paused, giving a clear condition for when to use. Lacks explicit when-not-to-use or alternative suggestions.

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

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

Without annotations, the description carries the full burden. It discloses that retrying reserves credit again, which is a notable side effect. However, it does not mention other behavioral traits such as idempotency, rate limits, authorization requirements, or failure/success responses.

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 two concise paragraphs with clear separation. The main action is front-loaded, and the Args section is structured logically. Every sentence adds value without redundancy.

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 tool's simplicity and the presence of an output schema (not shown), the description covers key aspects: purpose, cost implication, condition to use, and parameter details. It could be improved by mentioning idempotency or limits, but it is largely complete for a retry operation.

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 0% schema coverage, the description adds significant meaning: job_id is clarified as 'the job ID returned by create_survey,' and datapoint_indices is explained with the default behavior ('Omit to retry every failed datapoint'). This fully compensates for the lack of schema descriptions.

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 uses a specific verb 're-queue' and explicitly states the resource 'failed datapoints on a survey.' It clearly distinguishes this tool from sibling tools like cancel_survey or check_survey by focusing on retrying specific datapoints.

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 with 'only call this when the failures are worth recovering,' implying a cost-benefit condition. It also explains the default behavior when datapoint_indices is omitted. However, it does not explicitly state when not to use the tool or mention alternatives like checking survey status first.

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

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

Transparently describes the authentication flow: opens browser, signs in with Google, saves key locally, and never shares it. No annotations provided, so description carries full burden.

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?

Extremely concise: two brief paragraphs with no wasted words. Front-loaded with the verb 'Authenticate' and immediately explains the process.

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 no parameters, the description covers the essential authentication behavior. Could mention if already authenticated, but overall complete for a setup tool.

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?

No parameters exist, so schema coverage is 100%. Description adds context about the authentication flow beyond the empty schema, fulfilling the purpose.

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?

Clearly states the tool's purpose: authenticate with Datapoint AI. Explains the process: opens browser for Google sign-in and saves API key locally.

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?

Implies use for initial authentication, but does not explicitly state when to use versus alternatives like checking balance or creating surveys. No exclusions or prerequisites mentioned.

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

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

No annotations are present, so the description carries full burden. It explains the upload process, return format (dp:// refs), constraints (server rejects non-dp:///non-https://), and workflow integration. However, it does not mention potential limitations like file size, permissions, or failure modes, which prevents a higher score.

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 and well-structured: a clear purpose statement, followed by usage context, an example, and an exception. Every sentence adds value, and the example concretely illustrates the intended pattern.

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 that an output schema exists (mentioned in context), the description adequately covers the return value (dp:// refs) via text and example. It also clearly relates to sibling tools (plan_survey, create_survey). No critical information is missing for an AI agent to use this tool correctly.

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 schema has one parameter with no description coverage. The description adds significant meaning by stating that file_paths must be an array of absolute local paths to media files. This clarifies the expected format and domain beyond the simple 'string' type.

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 the verb (upload), resource (local media files), and output (dp:// references). It specifies supported types (images, audio, video) and distinguishes itself from other tools by being a prerequisite for plan_survey/create_survey when dealing with local files.

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 explicitly advises to use this tool before plan_survey/create_survey for any survey over local files, and notes that public https URLs do not need uploading. This provides clear when-to-use and when-not-to-use guidance, and explains the rationale (annotators cannot access local disk).

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