aso_unit_economics

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose what the tool produces (margin, break-even, warnings), the apple_cut default rule (0.15 Small Business, else 0.30), and its advisory role in validating scaffold credits. It does not state whether it is purely read-only, whether it persists anything, or whether it depends on project state, which is a gap given zero annotation coverage.

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 computation is front-loaded in a compact formula line, followed by one sentence of stage/relationship context and a default-value note. Little waste; the parenthetical credit note is slightly dense but earns 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 not be described, which the description correctly omits. But for a 6-parameter, zero-schema-coverage, annotation-free tool the definition is only partially complete: parameter meanings and side-effect/safety behavior are thin, and sibling differentiation from pricing_unit_economics is absent.

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% across 6 parameters, so the description must compensate. It explains apple_cut's default semantics and references the weekly/yearly credit inputs, but leaves weekly_price, yearly_price, ai_cost_per_credit, and yearly_monthly_credits entirely unexplained — no units, granularity, or accepted ranges.

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 states a concrete computation: 'credit count × AI cost vs subscription revenue → margin, break-even, warnings.' An agent can tell this is a unit-economics calculator rather than a mutating setup tool. However, it never distinguishes itself from the near-identical sibling 'pricing_unit_economics', which is the most likely source of misselection.

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?

It anchors usage to a phase: 'Grounds the price + credit decision in data at the idea/scaffold stage,' and ties it to app_scaffold via the credits it validates. That is implied when-to-use context, but there is no explicit when-not guidance and no routing away from the sibling pricing_unit_economics.

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