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

Annotations declare readOnlyHint and idempotentHint, aligning with the description's 'read' operation. The description adds valuable behavioral context beyond annotations: the TypeSafe key is never returned, the definition of a plan as a capacity model not a feature ladder, free plan limits, and what counts as a submission (e.g., spam/honeypot don't count). This exceeds the baseline for annotation-covered tools.

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 richly detailed but somewhat dense and rambling; it packs many details about plan features, limits, and expansion packs in a way that might overwhelm an agent. However, it front-loads the core purpose and includes a clear exclusion near the end, so it is structured but could be tightened.

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 complexity (plan details, token requirements, upgrade path), the description covers all necessary information: what is read, what is not returned, access control, and when to use alternatives. The output has no schema, but the description lists all return fields explicitly, making the tool's output predictable.

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%, and the schema already describes team_id and its conditional requirement. The description adds context about operator tokens needing team_id and team-scoped tokens possibly omitting it, which reinforces the schema but the schema already says the same, so it adds marginal value. Baseline 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 explicitly states the resource ('the team's plan'), lists the specific data fields returned, and distinguishes itself from siblings by noting 'Do not use this to list projects — call list_projects.' The verb 'read' and the concrete detail clearly establish its purpose and scope.

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, including token types (operator vs. team-scoped) and when to pass team_id, and an explicit exclusion ('Do not use this to list projects') with the alternative tool named. It also connects to sibling create_upgrade_link for upgrade flows, giving clear context for when this tool is NOT appropriate.

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