saas_api_get_agency_plans_deprecated

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

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the bar for additional disclosure is lower. The description adds the token requirement, which is useful context not present in annotations. It does not elaborate on response format, pagination, or errors, but these are less critical given the explicit safety hints.

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 concise sentence that front-loads the main action and includes the essential token constraint. It avoids redundancy and is efficiently structured, though it could be slightly expanded with sibling differentiation without losing 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 get operation with one parameter and no output schema, the description covers the purpose and a critical prerequisite. It lacks details on the returned data or any edge cases, but given the tool's simplicity and the safety annotations, it is minimally adequate without being comprehensive.

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 fully describes the only parameter `companyId` with 'Company ID to get agency plans for', so the description adds no extra semantic value. Per the rubric, with high schema coverage the baseline is 3; the description does not go beyond what the schema already conveys.

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 retrieves Agency Plans, which is a specific verb and resource. It also adds a key qualifier about the required token type, helping distinguish it from sibling tools. However, it does not explicitly contrast itself with the non-deprecated sibling `saas_api_get_agency_plans`, so it falls short of a perfect 5.

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 gives a usage prerequisite—requires an agency-level token, not a location PIT—which serves as a guideline for when this tool is appropriate. It does not, however, mention when to avoid it or point to the alternative non-deprecated tool, leaving part of the decision implicit.

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