getPlanById

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

With no annotations, the description carries the disclosure burden. It does add value by warning that the response is a comprehensive export rather than a summary, but it does not address read-only guarantees, error behavior, or the fact that providing last_knowledge_of_server narrows the result to changed entities. The word 'all' is also slightly too absolute given that filter.

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?

Two short sentences front-load the core behavior. The second sentence mostly restates the first, but the 'full plan export' analogy adds a useful size/scope signal that justifies its place.

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?

An output schema exists, so return values need no elaboration. Combined with the schema-documented parameters and the 'full plan export' framing, the description gives an agent enough to call the tool correctly; the only notable omission is explicit guidance about sibling selection.

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 plan_id and last_knowledge_of_server are already well documented in the schema. The description adds no parameter-level meaning beyond implying that the response includes related entities, which is the baseline expectation.

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 ('Returns'), names the exact resource ('a single plan'), and adds scope ('all related entities', 'effectively a full plan export'). This clearly distinguishes it from the list-oriented sibling getPlans and from other by-id getters.

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 'full plan export' phrasing implies this is the tool to use when a complete plan payload is needed, but it never names alternatives or states when not to use it. Siblings like getPlans or getPlanSettingsById exist, so the routing decision is left to inference.

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