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

Annotations already declare a read-only, closed-world, non-destructive operation, so the bar is lower. The description still adds real behavioral context: what the response contains (parameter schema plus response field descriptions), what extra block appears for service config methods, and what include_variables injects into the response. It does not discuss response size, caching, or behavior when method_name is unknown.

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 core purpose is front-loaded in the first sentence, and each following sentence covers a distinct conditional behavior rather than repeating the name. The parenthetical method lists are dense but carry needed precision; only the get_documentation aside feels slightly tangential.

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 no output schema, the description has to describe return values, and it does so concretely for the base case and both conditional cases. What remains thin is error behavior and how to discover valid method names, which matters for a lookup tool keyed on a free-text identifier.

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%, so a baseline of 3 would be acceptable, but the description adds meaning beyond the schema by tying each optional parameter to its conditional effect on the response (a service_types summary, config_schema or actions_schema for one type, and template variables/filters). It still does not clarify accepted method_name format beyond the schema's example or what happens with an unrecognized service_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 gives a precise verb and resource: it returns the full parameter schema and response field descriptions for one named Telerivet API method. It also scopes the conditional extras (service config methods, template-variable methods) and points to get_documentation for the Cloud Script API reference, so an agent can tell it apart from that sibling without opening either schema.

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?

Usage conditions are explicit: pass service_type only for Project_createService, Service_setConfig, or Service_getConfig, and set include_variables to true only for methods supporting [[variable]] syntax. It also routes the agent to get_documentation for the Cloud Script API reference. The one gap is that it never says how to obtain a valid method_name (e.g., via list_api_methods), so discovery of the required argument is left implicit.

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