Family System Pattern

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely new operational facts: the POST endpoint and a cost of 10 credits (Tier 1), which matter for budgeting calls. It says nothing about processing time, failure modes for bad birth data, or the 2-8 member bound.

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?

Front-loaded one-line purpose followed by bracketed metadata; nothing is padded. The structure is scannable, though the bracketed lines carry more weight than the single prose sentence does.

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?

This is a paid (10 credits), multi-chart, closed-world computation with an output schema, and the description never conveys what the system-level pattern reports or how many charts it expects. Given several overlapping family tools, an agent lacks the minimum needed to select it confidently.

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 description contributes only "[Required: members]" and misses the minItems 2 / maxItems 8 constraint and the role enum (parent, child, grandparent, sibling, spouse) that define a family system. The schema itself is unusually well documented for birth data, timezone and houseSystem, so the description's silence costs less than the 0% coverage figure suggests. Baseline 3.

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?

"System-level family astrological signatures" names the resource (family, system-level) but never states a specific verb or what a "signature" contains. It is distinguishable from single-chart tools, but among siblings astroway_family_genogram, astroway_family_parent_child_deep and astroway_family_sibling_dynamics there is no hint of what this one computes differently.

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?

There is no when-to-use statement, no prerequisites, and no named alternative. The only scoping cue is "[Required: members]", which is schema restatement rather than guidance. An agent has no way to choose this over family_genogram or relational_group_synastry from the text.

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