saas_api_get_saas_plan

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds the token requirement as an operational detail, but does not disclose return formats, pagination, or error conditions. With annotations handling the core behavioral traits, the one extra detail justifies a 3, though richer context would be welcome.

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 sentence, extremely concise and front-loaded with the main action. It wastes no words and immediately gives the critical prerequisite. While it may be too terse, it earns high marks for conciseness and structural efficiency.

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 tool has no output schema, so the description should explain what the tool returns, but it doesn't. It also omits parameter details, does not clarify how to obtain planId and companyId, and lacks context on when to use this versus the deprecated variant. Given the complexity of the SaaS domain and the missing information, the description is incomplete.

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%, so the description must compensate for parameter meaning. The description does not mention planId or companyId at all, nor their formats, sources, or constraints. Since the parameter names are only nominally self-explanatory and no additional guidance is provided, this is a significant gap.

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 'Get' and the resource 'SaaS Plan', making the purpose explicit. It also distinguishes itself from location-level operations by specifying 'requires an agency-level token, not a location PIT', which helps differentiate it from sibling tools like saas_api_get_location_subscription.

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 a clear usage condition (agency-level token required, not a location PIT), which implicitly tells agents when this tool is appropriate versus alternatives that operate on location-level tokens. However, it doesn't explicitly name alternative tools or state 'use this when...', so it's slightly less directive than ideal.

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