AstroWay Reports

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. Description adds that it returns a 'plain-text human-readable summary' and clarifies the budget-checking purpose, providing useful context beyond annotations.

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?

Three efficient sentences: purpose, usage guidance, and return format. Front-loaded with key information, no wasted words.

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?

Despite lacking an output schema, the description specifies the return format (plain-text human-readable summary). For a simple status check tool, this is complete and sufficient.

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?

Tool has zero parameters, so schema coverage is 100%. Description does not need to explain parameters, and it adds value by hinting at the output format.

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?

Description clearly states the verb 'Check' and the resource 'API key status' with specific attributes (tier, credit balance, rate limits, monthly cycle reset). It distinguishes itself from the many sibling astrology calculation tools.

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?

Explicitly instructs to run this tool BEFORE invoking expensive endpoints, providing credit thresholds (Tier 4+ at 100+ credits, Tier 6/7 at 500-5000 credits) to confirm budget.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds genuine behavioral context beyond them: executors are kept out of the vendor objects because an unexpected key causes a 400 on the vendor side, and cost is flagged as not in the public credit manifest. That is real operational value.

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?

Roughly three sentences, front-loaded with the purpose before the format and executor caveats. It is dense but each sentence carries information, though the format explanation partially duplicates the schema's own enum description.

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?

With an output schema present and full annotation coverage, the description need not explain return values, and it appropriately focuses on the vendor-shape contract and the executors/400 gotcha. It is nearly complete, with the only gap being sibling disambiguation rather than missing operational detail.

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 100%, so the schema already documents every parameter in depth (limit ceiling rationale, select values, precision semantics). The description only restates format and its default, adding no parameter meaning the schema lacks. Baseline 3 is correct.

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 what the tool returns: tool definitions for an agent framework, generated from the live OpenAPI document. It is specific about the resource and the vendor-shape variants (openai vs anthropic objects). However, it never distinguishes this from the near-identical sibling astroway_mcp_tools_list, which an agent would plausibly confuse it with.

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 explicit when-to-use, when-not-to-use, or alternative-naming guidance. The mention that openai objects 'spread straight into a chat completion' implies a use case, but the agent is left to infer when this endpoint is preferable to astroway_mcp_tools_list or the MCP tool-call streaming siblings.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety bar is low; the description still adds real value by clarifying that endpoints are NOT invoked and that results are cached with a 5-minute TTL. It also discloses the return shape (total + per-endpoint breakdown with tier annotations), which is meaningful since no output schema exists.

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?

Three tight sentences, front-loaded with the core capability and the non-invocation guarantee, followed by workflow guidance and the cache note. Nothing is wasted.

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?

Despite having no output schema, the description explains the return value, and the invocation-free and cache behaviors are covered. For a one-parameter, read-only estimator this is fully sufficient.

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 100% and the single 'endpoints' parameter is fully documented with examples and the leading-slash rule in the schema. The description only restates 'one or more endpoints' without adding format or constraint detail beyond the schema, so baseline 3 applies.

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?

States a specific verb and resource ('Estimate the credit cost of one or more endpoints') and immediately pins the scope with 'WITHOUT invoking them', which no sibling tool does. An agent can distinguish this from the many invocation/report siblings at a glance.

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?

Gives explicit workflow guidance: 'estimate first, ask user confirmation, then invoke' for multi-step planning. This is clear when-to-use context, though it names no alternative tool or when-not-to-use condition.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely useful operational context — cost (100 credits, Tier 4), the required-parameter set, and the endpoint. It stays silent on runtime behavior an agent might care about, such as whether the multi-round debate is long-running, streamed, or bounded in output size. The POST endpoint is not a contradiction of readOnlyHint, but it is worth noting.

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?

Tight and well front-loaded: the core operation comes first, then compact bracketed metadata. Every line carries information (endpoint, required fields, cost) rather than filler. Its brevity is a virtue, though it edges into under-specification.

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. But for an 8-parameter tool with a nested chart object, aless-than-40% coverage, and a cost of 100 credits, the description leaves critical gaps — most importantly the semantics of agentA/agentB and the effect of rounds/language.

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 only 38%, so the description carries a heavier burden, and it does not meet it. It restates the three required parameters that the schema already marks as required, but never explains what agentA/agentB actually are (persona strings? model IDs?) or what topic expects. Optional params like rounds, language, and fields get no mention.

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?

Uses a specific verb-and-resource phrasing: '2 personas debate a topic, multi-round transcript.' An agent can grasp the operation immediately. However it does not differentiate itself from close siblings such as astroway_mcp_multi_agent_coordinate, astroway_mcp_ai_chat, or astroway_mcp_ai_comparison_coach, which plausibly overlap.

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 guidance and no named alternative. The bracketed metadata lists required fields and cost but never says when this debate tool is preferable to multi-agent coordination or AI chat. The [Group: MCP Advanced] tag is organizational, not decision-supporting.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint false, and openWorldHint false. The description adds useful behavioral context in the form of the cost (10 credits, Tier 1) and HTTP method (GET), but does not describe what the status output contains or any auth/rate-limit details.

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 text is short but poorly structured: a vague fragment followed by bracketed metadata lines. It is under-specified rather than concise, and the opening line does not front-load a clear purpose.

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?

Although an output schema exists and annotations cover the safety profile, the description still leaves the agent without a clear statement of what the tool does or when to call it. For a status endpoint in a large sibling set, this is a significant omission.

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 100%, so the two optional parameters (fields, precision) are fully documented in the schema itself. The description adds no parameter meaning beyond the schema, so the baseline of 3 applies.

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 gives only a fragment, '8 personas with specialties,' which hints at pool composition but never states that this tool returns agent pool status or what that status contains. It lacks a clear verb and resource, and does not distinguish itself from siblings like astroway_mcp_multi_agent_coordinate or astroway_agent_tools.

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 guidance on when to use this tool, when not to use it, or which sibling tool is the alternative. The description contains only metadata tags, not usage instructions.

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

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

Annotations already declare read-only, non-destructive, open-world behavior, so the bar is lower; the description still adds real behavioral facts beyond them — a 10-turn history ceiling, 21 output languages, four selectable voices via persona, and a concrete pricing rule (5 credits with your own provider key vs. the endpoint price). It stops short of stating auth requirements or what happens when the history limit is exceeded. No contradiction with annotations.

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?

Three tight sentences: the differentiator first, capabilities second, pricing last, followed by a compact metadata block (group, endpoint, required param, tier cost). Every clause carries new information and nothing is repeated from the schema.

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?

With an output schema present the description needn't explain return values, and annotations cover the safety profile, so what remains — what the tool is for, its capability envelope, and its cost model — is covered. The main gap is that nothing tells an agent when this endpoint should be picked over the other AI/agent siblings.

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?

Top-level schema description coverage is only 43% (chart, fields and precision documented; message, persona, language and history not), so the description must compensate and partially does — it explains persona (four voices), history (~10 turns) and language (21 options). It says nothing about chart, fields compact-mode paths, or precision, though the nested chart schema does carry unusually rich self-documentation for those.

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?

States a specific verb and resource — an AI chat answered from computed natal-chart positions rather than the model's prior knowledge of a sun sign — and quantifies scope (10 turns, 21 languages, 4 personas). It clearly implies a different product from sibling AI utilities such as astroway_mcp_ai_explain_aspect or astroway_mcp_ai_comparison_coach, but never names them, so the differentiation is by tone rather than explicit contrast.

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?

Usage context is implied rather than stated: the credit-price note ('send your own provider key and the turn costs 5 credits instead of the endpoint price') hints this is a paid, higher-tier call, and 'chart-grounded' hints the input needs birth data. There is no explicit when-to-use-it, when-not-to, or routing rule against the other chat/agent endpoints in the sibling list.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely useful operational context (the 100-credit Tier 4 cost and the POST endpoint), but says nothing about the fact that an LLM-backed coach may return non-deterministic prose, what latency to expect, or what deprecates the idempotentHint=false signal.

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 four lines are tight and the purpose sentence is front-loaded ahead of the bracketed metadata block. Nothing is padded, though the metadata lines are boilerplate rather than definitional content.

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 explained, and the cost/endpoint block is present. But for a six-parameter AI tool embedded among dozens of similar compatibility siblings, the description lacks any hint of what the coaching output contains or what makes a good 'question', leaving the agent to guess at scope.

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 67% and the nested chart objects carry extensive inline documentation (formats, rejected short names, timezone semantics, houseSystem letters), so the schema does the heavy lifting. The description only restates the required parameters (chart1, chart2, question), adding no meaning for question, language, fields or precision. 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 names a specific verb (coach), the resources (two charts) and the domain (relationship dynamics), so the agent knows this produces interpretive guidance rather than raw chart data. It does not, however, distinguish itself from the many sibling compatibility tools (ashtakoot, dashakoota, compatibility_full) or from astroway_mcp_ai_chat, so sibling differentiation is left to inference.

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 or when-not-to-use guidance, and no alternative is named. A reader cannot tell whether to reach for this AI coach versus the deterministic Vedic compatibility endpoints or multi_chart_context. The only constraints given are required parameters and cost, which are not usage guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true and idempotentHint=false, so the safety profile is covered without the description. The description does add genuinely useful operational context not present in the annotations: the credit cost (100 credits, Tier 4) and the endpoint. However it never explains why a read-only operation is flagged non-idempotent (repeated calls likely yield differently worded narrative), which is the one behavioral trait an agent would most want here.

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 purpose sentence is front-loaded and the payload is small. The '[Required: planet1, planet2, aspectType]' line duplicates the schema's required array, but the cost and endpoint lines justify their space.

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. But for a 7-parameter tool with a nested chart object and LLM-backed generation, the description omits the valid domain for planet1/planet2, any usage guidance versus explain_transit, and any hint about generation latency or variable output.

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 lists the three required parameters, but schema coverage is only 43% and planet1/planet2 carry no description, no enum and no example anywhere in the schema, so the agent must guess the accepted form (planet names such as 'Mars'?). The description does not compensate for that gap, which is the weakest part of the definition.

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?

Names a specific verb and resource: 'explanation of an aspect between two planets.' An agent can tell it apart from the sibling astroway_mcp_ai_explain_transit by the resource alone, but the description never makes that contrast explicit nor states what kind of explanation is produced.

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 guidance, no prerequisites, and no mention of the sibling explain_transit as an alternative. The only contextual cues are bracketed metadata (endpoint, required fields, credit cost), which tell the agent what it costs but not when it should be chosen.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully adds the cost (100 credits, Tier 4) and the endpoint, which annotations do not provide. It does not explain why idempotentHint is false for a read-only call, nor what the AI explanation entails.

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 short and front-loads the purpose before the bracketed metadata. The bracketed group/endpoint/required/cost lines are slightly noisy but each carries compact information, so there is little waste.

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. But for a 5-required-parameter tool with a near-twin sibling, the description omits the disambiguation, parameter usage, and cost implications an agent needs before committing. It is minimally adequate rather than complete.

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 only 38%, so the description should compensate, but it merely restates the five required parameter names that the schema already marks required and says nothing about what transitPlanet, natalPlanet, aspectType accept or how the optional fields/precision/language parameters behave. It adds no meaning beyond the schema.

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?

States a specific verb and resource: 'Explain a current transit hitting your natal chart.' An agent can grasp the purpose immediately. However, it never distinguishes itself from the close sibling astroway_mcp_ai_explain_aspect, leaving the borderline case ambiguous.

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 guidance, no exclusions, and no comparison to the near-identical sibling astroway_mcp_ai_explain_aspect. The '[Required: ...]' and '[Cost: ...]' lines are metadata, not routing guidance. The agent gets no help deciding between this and other AI tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description usefully adds the cost (100 credits, Tier 4) and the endpoint/group, but says nothing about latency, response shape of the synthesis, or how many personas are permitted (schema caps at 4).

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 with the operative sentence, followed by compact bracketed metadata; there is no filler prose. The brevity is close to under-specification rather than pure conciseness, keeping it out of the top band.

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, and cost is disclosed. However, for a tool whose whole contract is choosing personas and a question, the description never explains what the agents array should contain, leaving the most decision-relevant input undocumented across both description and schema.

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 only 50% and the description adds no meaning beyond listing the two required names. Critically, the 'agents' array is the defining parameter and neither the schema nor the description explains what identifiers it accepts, and 'question' semantics are equally unexplained.

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?

States a specific verb (Run), resource (N personas) and mechanism (parallel + LLM synthesis), which is more informative than a tautology. It does not name or distinguish itself from the obvious sibling astroway_mcp_agent_debate, so the agent must infer the difference between coordinated parallel personas and a debate.

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?

No when-to-use guidance, no prerequisites, and no alternatives are named despite several closely related siblings (agent_debate, multi_chart_context, ai_chat). The '[Required: question, agents]' line just restates the schema's required array rather than telling the agent when this tool is the right choice.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful non-annotation behavior: a 10-credit (Tier 1) cost and the POST endpoint. It says nothing about what the operation returns or how it behaves across the 1-6 chart array, so it earns only partial credit.

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?

It is short and front-loads the one-sentence purpose, with well-organized bracketed metadata. But that metadata is machine-oriented boilerplate (group/endpoint/required) and the prose line is largely redundant with the title, so the brevity reflects under-specification as much as discipline.

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 explained, but for a tool taking up to six nested chart objects with four intent modes and compact-mode fields/precision, the description is far too thin. It gives an agent no way to know what a "compatibility" vs "forecast" run produces or why to pick it over the many neighbouring multi-chart tools.

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 only parameter content is "[Required: charts]", which merely repeats the schema's required array, adding zero meaning. The description says nothing about `fields`, `precision`, or the four `intent` modes — the latter has no schema description at all despite being the main selector. At 50% schema coverage this is a real gap it fails to fill.

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?

"Compact context for MCP agents working across multiple charts" largely restates the name/title (multi-chart context) without naming an action or an output. The word "context" is undefined — it never says whether this computes cross-chart aspects, comparison summaries, or group forecasts. Only the bare notion "multiple charts" distinguishes it from the many single-chart siblings.

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 guidance at all: no trigger conditions, no prerequisites, and no routing against the large sibling set (e.g. astroway_mcp_multi_agent_coordinate or astroway_mcp_ai_comparison_coach). The `intent` enum (compatibility/family/group/forecast) suggests several distinct use cases, but the description never explains when to choose which.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds genuinely useful context the annotations do not: the endpoint, the 10-credit Tier 1 cost, and the group. It does not disclose result ordering, chunk granularity, or hit limits, so it stops short of rich behavioral context.

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?

Four short, front-loaded lines with no prose padding; the core purpose statement leads. The "Required" line is redundant with the schema, which is the only real waste.

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 tool taking a deeply nested chart object plus three tuning parameters, the description is thin: no sense of ranking/scoring semantics, no indication of what the chunks are drawn from, and no guidance on choosing topK. An output schema exists so return format need not be explained, but the retrieval behavior itself is left entirely to inference.

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 a middling 60%. The description adds no parameter meaning at all — it only echoes the two required names already enforced by the schema — and says nothing about topK's default/range, the fields compact projection, or precision, the parameter most likely to be misused.

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?

Names the mechanism (keyword-tag scoring) and the corpus (chart chunks), which goes beyond simply restating the tool name. However, it never says what the tool returns or what a "chunk" is, so an agent cannot tell whether this is a document retriever over interpretive text or a query over computed chart data.

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 only usage-adjacent line is "[Required: query, chart]", which merely restates the schema's required list. There is no statement of when to reach for this tool rather than a direct retrieval sibling (e.g. astroway_mcp_multi_chart_context), and no prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds genuinely non-derivable behavior: the response is delivered as an SSE stream rather than one payload, crediting at 100 credits (Tier 4), and the concrete endpoint. It omits auth requirements and why idempotentHint=false, which keeps it out of 5 territory.

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?

Short and front-loaded: the core capability leads, with bracketed metadata (group, endpoint, required param, cost) following compactly. Every line carries information, though the template-style [Group:]/[Endpoint:] format is more machine header than prose.

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 streaming tool with no output schema and a nested chart parameter, the definition covers the essential facts (SSE transport, required message, optional chart, cost). It does not describe what the stream emits or how chart context influences the completion, leaving gaps an agent would notice mid-invocation.

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 60%, with the nested chart object heavily documented in the schema itself (timezone, houseSystem letters, lat/lon full names, ayanamsa). The description adds only 'optional chart context', which restates the schema's required list. Baseline 3 is appropriate when the schema does most of the work.

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?

States a specific verb+resource+mechanism: 'Server-Sent Events streaming chat completion with optional chart context.' An agent can tell this is a streaming chat tool rather than a static computation. It does not explicitly name or contrast with the closest sibling astroway_mcp_ai_chat, so it stops short of a 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?

No when-to-use or when-not-to-use guidance. Nothing tells the agent to prefer this over astroway_mcp_ai_chat (non-streaming chat) or astroway_mcp_tool_call_stream; the streaming qualifier implies a context but the choice is left entirely to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds two genuinely useful behavioral facts annotations cannot express: delivery is server-sent events rather than a single response, and the call costs 10 credits (Tier 1). It still omits stream termination, error-over-stream behavior, and whether partial results can be replayed.

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?

Very short and front-loaded: one sentence of purpose followed by structured metadata brackets. Nothing is wasted, though the single sentence is so compressed that the core mechanics of the tool are never actually spelled out.

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 5-parameter tool with a nested free-form args object, a free-text tool selector, compact-mode options, and no output schema, this is under-specified. An agent cannot tell what the stream emits, how to consume it, or what valid values for tool are (presumably must match astroway_mcp_tools_list entries), all of which are load-bearing here.

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 only 40% across 5 parameters, and the description adds nothing beyond confirming that tool is required. args (arbitrary nested object forwarded to the target tool), language, and the compact-mode interplay of fields/precision are left entirely to the schema; the description should explain that args are passed through verbatim to the named tool.

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?

"SSE-stream of a tool call envelope" names a delivery mechanism and an artifact, so the agent knows this is a streaming wrapper that executes a named tool. However, "tool call envelope" is opaque jargon and the definition never states the key fact that this proxies/executes another MCP tool by name, nor how it differs from the sibling astroway_mcp_streaming or astroway_mcp_tools_list.

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 only usage cue is the bracketed "[Required: tool]" — there is no when-to-use, no when-not-to-use, and no routing to an alternative despite multiple plausible siblings (astroway_mcp_streaming, astroway_mcp_tools_list, astroway_agent_tools). The agent must guess whether streaming is preferred over a plain call.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context the annotations do not: the concrete GET endpoint and a cost caveat that this scope is not in the public credit manifest. It does not explain response size or pagination for a manifest that presumably enumerates all 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 single purpose sentence is front-loaded and the metadata tags are compact, but the bracketed group/endpoint/cost lines are boilerplate scaffolding rather than description content. Nothing is wasted, yet very little informational payload is delivered.

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-value documentation is not required, but for a meta-tool that enumerates the entire tool surface, the description never explains the scenario in which an agent would reach for it instead of directly invoking a domain tool. Given the enormous sibling set, this leaves a real gap.

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 100%, so both `fields` and `precision` are already documented in the schema with examples and constraints. The description contributes no additional parameter meaning; the 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?

"Auto-generated tool manifest for MCP clients" largely restates the name 'MCP Tools List' without a distinct verb or an explanation of what the response actually contains. It gives an endpoint and spec version but no functional description that would distinguish its purpose from any other listing endpoint.

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 statement of when an agent should call this tool, what problem it solves, or how it relates to the ~190 sibling tools. The only contextual cues are the bracketed [Group]/[Endpoint]/[Cost] metadata tags, which are not usage guidance.

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

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

Annotations already declare readOnly=false, idempotent=false, destructive=false, openWorld=true, so the safety profile is covered. The description adds material behavioral context beyond that: the 250-credit Tier 5 cost and the requirement to confirm with the user first, which is genuinely decision-relevant. It does not describe side effects or result handling, keeping it out of 5 territory.

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 purpose is front-loaded, then structured metadata lines (group, endpoint, required, cost) carry the rest with no filler. Every line earns its place, though the bracketed tag block is somewhat boilerplate rather than prose that aids selection.

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?

With an output schema present, the description need not explain return values, and it covers purpose, required inputs, cost and a confirmation warning. The main gap is that two optional parameters (fields, precision) and the tone/length/language semantics are left entirely to the schema.

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 only 38%, so the description is expected to compensate. It lists chart, year, month, language, tone and length as inputs but adds meaning only for month ('1-12'), leaving fields and precision unmentioned and tone/length/language values unexplained. This is minimum-viable, not compensating for the coverage gap.

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 names a concrete resource ('single-month forecast') and explicitly scopes it ('uses fast and slow planet transits within the month'), which lets an agent separate it from the year-ahead sibling. The verb is implicit rather than stated ('generate a narrative'), but the purpose is unambiguous.

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 explicitly contrasts scope with the year-ahead sibling ('Tighter scope than year-ahead'), giving a selection cue, and adds a strong operational directive: 'Heavy — confirm with user before invoking' at Tier 5 / 250 credits. No exclusion rules against the natal/synastry/transit narrative siblings are given, so it falls short of a 5.

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

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

Annotations already disclose openWorld/not-idempotent/not-read-only behavior, and the description adds value beyond them: the exact credit cost, the heavy/confirm-first warning, the output shape (narrative text plus model and token usage), and the ≤3200-token length cap. The grounding scope (Sun/Moon/Asc, 13 bodies, 12 houses, ≤25 aspects) is genuinely informative behavioral context.

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 with the core purpose, then inputs, then return values, then a bracketed metadata block. Every line carries information (group, endpoint, required, cost). Slightly dense but no wasted prose.

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 fully enumerated, yet the description still notes them briefly. Required param, cost/tier, grounding detail, and token budget round out what an agent needs. The only shortfall is that fields/precision semantics are left entirely to the schema.

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 only 50%, so the description must compensate. It covers chart, language ('21 codes'), tone (warm/professional/concise) and length (short/medium/long; ≤3200 tokens), which is useful. However, it omits meaning for the compact-mode params fields and precision, which the schema carries, leaving a partial gap. 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?

States a specific verb+resource: 'Long-form natal-chart narrative (markdown)' grounded on a computed natal chart. This clearly separates it from the AI monthly/synastry/transit/year-ahead narrative siblings. It does not, however, explicitly contrast with astroway_reports_natal or astroway_ai_interpret_natal, so sibling differentiation is incomplete.

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 metadata block gives a crucial usage cue: 'Cost: 250 credits (Tier 5)' and 'Heavy — confirm with user before invoking.' That is real when-to-invoke guidance. But there is no explicit routing against alternatives (e.g., when to prefer the non-AI reports_natal or a shorter narrative variant), so usage is only implied.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the mutation/regeneration profile is partly covered. The description adds material context the annotations do not: cost of 250 credits at Tier 5, the 'Heavy' flag, and the explicit instruction to confirm with the user first, which is exactly the kind of operational disclosure that matters.

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?

One front-loaded sentence gives the purpose, followed by a compact bracketed metadata block (group, endpoint, required, cost). No wasted prose, though the metadata is appended rather than integrated into the prose flow.

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 explained. Required parameters, cost, heavy-invocation warning, and endpoint are all present, giving an agent everything needed to decide and call correctly.

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 57%, and the description only enumerates chart1, chart2, language, tone, length by name without adding format, defaults, or semantic meaning. The nested chart-object details live entirely in the schema, so the description does not compensate for the coverage gap but the enumeration is a marginal help. 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?

States a specific output (long-form relationship narrative) with its basis (cross-chart aspects), which distinguishes it from the natal/transit/monthly/year-ahead narrative siblings. It does not, however, explicitly contrast itself with the closely-related astroway_reports_synastry or astroway_ai_interpret_synastry tools, so the agent must infer the boundary.

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 'Heavy — confirm with user before invoking' warning plus the 250-credit cost is genuine usage guidance and the required params are listed. But there is no explicit when-to-use-vs-alternative routing (e.g. why this over astroway_ai_interpret_synastry), leaving the selection rationale implied.

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

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

Annotations already declare readOnlyHint=false/openWorldHint=true/idempotentHint=false, and the description adds genuinely useful behavioral context: it is a POST endpoint, costs 250 credits (Tier 5), and is flagged heavy enough to require user confirmation. It does not cover auth or rate limits, but the cost/confirmation disclosure is real added value.

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-loads the core purpose in the first sentence, then inputs and output basis, with metadata lines clearly separated. Efficient with little waste, though the input listing is both inaccurate and space-consuming.

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?

Output schema exists, so return-value explanation is unnecessary, and the cost/heaviness warning is present. But the parameter-description mismatch leaves the agent unable to reliably map inputs, which is a meaningful completeness gap for an 8-param tool.

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 lists inputs 'chart + transitDate (+optional transitTime/tzOffset), language, tone, length', but the schema exposes date, time, fields, ayanamsa, ayanamsaId, timezone, timezoneOffset, precision. Several named inputs (chart, language, tone, length) do not exist, and the actual compaction params (fields, precision, ayanamsa) are ignored — the description misleads rather than supplements the 63%-documented schema.

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?

States a specific verb+resource: 'Snapshot transit interpretation for a specific date' returning a narrative. The 'single date' scope implicitly distinguishes it from monthly/year-ahead narrative siblings, but no sibling is named explicitly, so differentiation relies on inference.

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?

Conveys when this applies (a single-date transit reading) and adds a critical 'confirm with user before invoking' warning tied to the 250-credit cost. However, it never explicitly contrasts against the many transit/report siblings (e.g. astroway_ai_interpret_transits, astroway_reports_transit_yearly), leaving alternative selection to inference.

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

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

Annotations only declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds genuinely novel behavioral context the annotations lack: a 250-credit Tier 5 cost and an explicit instruction to confirm with the user before invoking. It does not describe output size/latency, but the cost disclosure is the key operational trait.

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 with the purpose sentence, then inputs, then bracketed metadata for group/endpoint/required/cost. Every line carries information; no filler or redundancy.

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 an output schema exists, return format needn't be explained, and the description covers the core intent, required input, cost, and a key default. The only gap is sibling differentiation and fuller parameter coverage for a 7-param tool with a nested chart object.

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 43%, so the description should compensate more than it does. It names most key inputs and adds real semantics not in the schema ('year default = next year', 'use long for full annual report'), but leaves fields and precision unexplained. It adds moderate value over the structured fields.

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?

States a specific verb and resource: a long-form annual report that combines natal context with the year's major outer-planet transits clustered by month. It is clearly distinct from the monthly/transit/synastry narrative siblings by scope, though it never names the alternative it differs from.

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?

Provides useful invocation guidance ('use long for full annual report') and a strong cost warning ('Heavy — confirm with user before invoking'), which shapes when to call it. However, it never contrasts this tool with the nearby alternatives (monthly narrative, transit narrative, transit_yearly), so selection among siblings 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.

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

Annotations declare this is a non-read-only, non-idempotent, open-world operation, and the description adds genuinely new behavioral context beyond that: a premium per-call cost, an explicit instruction to confirm before invoking, and a 'not financial advice' disclaimer that signals the report's liability scope. It does not cover async/PDF delivery timing or credit-refund behavior on failure.

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?

Three compact statements: what the report analyzes, what it highlights, and the disclaimer, followed by a bracketed metadata block with endpoint, required param, and cost. Front-loaded and free of filler, though the planetary parenthetical list is slightly dense relative to the rest.

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-value documentation is not required. For what remains — the expensive, confirm-first nature of the call, the required chart input, the endpoint, and the scope limitation implied by the disclaimer — the definition is complete. An agent has everything it needs to decide and invoke.

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 60% and the nested chart object carries very rich inline documentation (date/time formats, timezone handling, houseSystem letters), so the schema does the heavy lifting. The description adds no parameter information at all — notably nothing about language, whitelabel branding, or the compact-mode fields/precision options — so it neither compensates for the uncovered 40% nor adds beyond the schema. 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 names a concrete deliverable (a founding-chart business astrology report) and enumerates the content it emphasizes (Sun/purpose, MC/reputation, Jupiter/growth, Saturn/structure), which distinguishes it from the many astroway_business_* analysis tools that compute raw factors rather than a report. It never states the output medium (PDF or HTML) in the body text — that only appears in the title — and states no verb, so it is clear but slightly implicit.

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 bracketed cost line gives real usage guidance: 5,000 credits / Tier 7, roughly half the free monthly budget, confirm with the user first. That is the strongest routing signal here. However there is no guidance on when to pick this report over sibling reports (business_founding_chart, reports_career, reports_money) or what input conditions make it appropriate.

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

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

Annotations declare it is a non-read-only, non-idempotent, open-world write, but add nothing about cost or approval. The description fills exactly that gap with a precise price (5,000 credits, Tier 7), a relative-budget warning (~50% of free monthly budget) and an explicit user-confirmation requirement. It does not describe latency or what the returned artifact looks like, but the output schema covers the latter.

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-loads the substantive content list in the first sentence, then a scannable metadata block with group, endpoint, required param and cost. Every element earns its place; the only slight redundancy is restating the required parameter that the schema enforces.

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 paid generative report tool with an output schema, the description supplies the pieces an agent cannot infer: cost tier, budget impact, approval requirement, and the report's thematic scope. The remaining gap is sibling routing (natal vs career vs money reports), which matters given the large reports_* family.

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 only repeats the required-parameter fact ('Required: chart'), which the schema already enforces, and says nothing about fields, language, precision or whitelabel. With schema coverage at 60% and rich nested chart documentation in the schema, the description neither adds meaning nor compensates for the undocumented half; 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?

Names a specific resource (career-themed natal report) and enumerates the astrological content it covers (MC, 10th-house cusp, Saturn, Mars, aspects to Sun), which clearly separates it from reports_natal, reports_money or reports_love. It never states the verb explicitly in the description body (the title carries 'Generate ... PDF or HTML'), but the intent is unambiguous.

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?

Gives a framing constraint ('Self-knowledge tool, not directive') and a strong invocation precondition (confirm with user before invoking due to cost). However it never says when to choose this over sibling report tools such as astroway_reports_natal or astroway_reports_generate, so routing among the many report siblings 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.

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

Annotations already declare the non-read-only, non-idempotent, open-world profile, so the description's job is to add what they cannot. It does that well by disclosing the credit cost, the tier, the share of a free monthly budget, and the requirement to confirm before calling — genuinely decision-relevant behavior. It stops short of billing failure modes or auth expectations, so not a 5.

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?

It is front-loaded with the report's identity and content before the bracketed metadata block, and every line carries information (group, endpoint, required input, cost). The emoji/warning formatting is dense but not padded.

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?

With an output schema present, return values need not be explained, and annotations cover the safety profile; the description fills the remaining high-stakes gap (cost, confirmation, content scope). It is slightly incomplete in that the advertised output formats and the choice against sibling report tools are never addressed.

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 says nothing about any of the five parameters (chart, fields, language, precision, whitelabel); schema coverage is a middling 60%, with language and parts of whitelabel carrying no textual description in the schema either. The one concrete hint, 'PDF or HTML' in the title, maps to no parameter at all, so the description does not compensate for the coverage gap.

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 names the artifact ('Parenting-oriented natal report') and enumerates its distinguishing content (Moon, Mercury, Venus, Mars interpretations), which tells an agent this is the child-focused report rather than a generic one. It does not, however, explicitly distinguish itself from close siblings such as astroway_reports_natal or astroway_reports_generate, leaving the agent to infer that distinction from the name.

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 block supplies an invocation precondition — a 5,000-credit Tier 7 cost with an explicit 'Confirm with user before invoking' instruction — which is real usage guidance. But it never states when to choose this report over the numerous alternative report siblings (natal, business, career, synastry), so alternative selection is only implied by the 'child/parenting' framing.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the bar is lower. The description still adds real behavioral context: the document is pinned by a test to never disagree with the JSON endpoint, and it enumerates exactly what each page carries, including the auspicious first-wear day found by scanning. It omits cost/credit behavior and any storage or retrieval detail.

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 output format and the sibling relationship are front-loaded, and the subsequent inventory of document contents is genuinely informative rather than filler. There is some flourish ('What the document adds is what a table cannot carry'), and the enumeration is long, which keeps it from a 5.

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 explained, and the description instead covers document composition, the determinism guarantee, and the format switch. For a 7-parameter premium report tool it is largely complete, though it says nothing about the drawing-down of credits or the unmentioned localisation/whitelabel options.

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?

With schema coverage at 43%, the description is expected to compensate, and it does add meaning for some parameters: 'same two schools' clarifies the `school` enum, and the 'next auspicious day to first wear it' scan relates to `wearingFrom`. However, `language`, `whitelabel`, `fields` and `precision` are never addressed, so the compensation is partial.

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 identifies a specific resource (the ratna/gemstone prescription) and output form (multi-page A4 PDF by default, HTML with `?format=html`), and explicitly distinguishes it from the data sibling by stating it carries the same astrology as `POST /vedic/gemstones` but adds what a table cannot. The opening is a noun phrase rather than an explicit 'generate' verb, and it does not distinguish itself from other report siblings, so it falls short of a 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 relationship to `POST /vedic/gemstones` is stated (same result, richer document), which implies when to prefer this tool, but no explicit when-to-use/when-not-to-use rule is given. The premium cost and 'confirm with user' caution live in context signals, not the description text, so routing guidance is only implied.

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

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

Annotations already carry the behavior profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds cost context ('10 credits (Tier 1)') and how inputs vary, but says nothing about generation latency, what resource is produced, or auth needs. It is accurate and non-contradictory but adds only modest behavioral detail.

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 with the dispatch purpose, then the type enum, then the required-field rules; every sentence carries signal. The full report_type enum is duplicated from the schema and the bracketed metadata lines add some clutter, keeping it just short of maximally tight.

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 an existing output schema (returns need no explanation) and annotations covering the safety profile, the description is complete on the core dispatch mechanism and the per-type input requirements, which is what an agent needs to invoke it. It leaves the numerous optional parameters (depth/extended pricing, whitelabel, language, fields, precision) to the schema, which is acceptable but not exhaustive for a 14-parameter tool.

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 only 43%, so the description must compensate, and it does so for the critical part: the JSON schema marks only report_type as required, whereas the description supplies the conditional requirements (chart for most types, chart1+chart2 for synastry, seed with optional chart for tarot). This is genuine information the schema cannot express, though it does not describe the optional controls (depth, whitelabel, language, precision).

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?

States a specific verb and resource ('Generate Report'), declares the scope ('Single endpoint over the 12 type-specific renderers'), and enumerates all 12 report_type values. This lets an agent immediately distinguish it from the per-type sibling tools (astroway_reports_natal, astroway_reports_synastry, etc.) as the unified dispatcher.

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?

Clearly frames the dispatch model ('pass report_type plus the renderer-specific inputs', 'one method instead of 12') and gives the required inputs per type (chart for most, chart1+chart2 for synastry, seed for tarot). It stops short of explicitly naming when to prefer this over an individual per-type renderer endpoint or stating exclusions, so it is context-rich but not fully prescriptive.

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

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

The annotations declare readOnlyHint=false and idempotentHint=false, but the description (matching the GET /v1/reports/history endpoint) presents a read-only, repeatable listing — 'List...', 'Re-fetch a report link', 'Free to call'. The description's implied read-only, idempotent profile directly contradicts those two annotations.

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 with the purpose in the first sentence, then layers on lifecycle, cost, and pagination. Dense but every sentence earns its place; only slightly long for a two-optional-param listing call.

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 restated, and the description covers the non-obvious operational facts: 24h purge, `expired: true` with now-dead URLs, `retain_days`, cost, and the limit range. Minor gap: it never mentions the compact-mode `fields`/`precision` behavior present in the schema.

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 100%, so the schema already documents `fields` and `precision`; the baseline is 3. The description adds a `?limit=` (1–50, default 10) param that is absent from the schema, but says nothing about the two compact-mode params that are actually in the schema, so it neither compensates nor explains.

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?

States a specific verb (List) and a precisely scoped resource (the calling key's most recently generated PDF reports) and even enumerates the returned fields (type, size, page count, language, timestamps, url). Among the many reports_* and render_* siblings, it is immediately identifiable as the export-history listing tool.

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?

Gives two concrete use cases (re-fetch a report link while it lives, or surface recent exports in a dashboard) and the retention condition that governs validity. It does not name or exclude a sibling (e.g., the reports_generate tools), so the routing guidance is clear but not complete.

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

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

Annotations cover the write/idempotency profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true). The description adds context annotations cannot carry: the 5,000-credit Tier 7 cost, its share of the free budget, and the instruction to confirm with the user — meaningful for an expensive, non-idempotent generation call. It still says nothing about what is produced (URL, bytes, storage).

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 with the content inventory, followed by compact bracketed metadata for group, endpoint, required param and cost. Little waste, though the bracketed block partially restates what structured fields already convey.

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?

With an output schema present, return values need no explanation, and the cost/confirmation guidance is the most important missing piece — it is covered. But a tool taking whitelabel, language and compact fields produces a document whose format is only implied ('Bodygraph PDF' vs the title's 'PDF or HTML'), leaving the delivery format ambiguous for a premium call.

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 60%, and the schema itself does the heavy lifting, especially for the deeply-documented chart object. The description only flags 'Required: chart' and adds no meaning for fields, language, precision, or whitelabel. 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?

States a specific verb+resource (generate a Human Design report / bodygraph PDF) and enumerates exactly what the document contains: Type, Strategy, Authority, Profile, Definition, Not-Self theme, Incarnation Cross, 9 centers, activated channels. This distinguishes it from the raw-data sibling astroway_hd_human_design, though it never names that alternative explicitly.

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 cost tag gives real operational guidance ('Confirm with user before invoking', ~50% of free monthly budget) and 'Required: chart' sets the precondition. However, it never says when to choose this report tool over astroway_hd_human_design or the generic astroway_reports_generate, so routing 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.

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false. The description adds meaningful context beyond them: a concrete credit cost and tier, a premium-budget warning prompting user confirmation, and the compute method (Lahiri ayanamsa, sign-from-Lagna house numbering). This is exactly the kind of cost/side-effect disclosure annotations cannot carry.

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 front-loaded sentences covering contents and compute method, followed by a compact bracketed metadata block (group, endpoint, required, cost). No filler; every line carries information the agent needs.

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, and the description covers contents, compute convention, required parameter, and cost. The main omissions are the output format (PDF/HTML, present only in the title) and routing against the sibling report/granular tools.

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 60% with 5 parameters (chart, fields, language, precision, whitelabel), so the schema already documents much. The description only says '[Required: chart]' and never explains fields, language, precision, or whitelabel, and its Lahiri/ayanamsa note describes fixed compute rather than advising how to set those parameters. 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?

States a specific verb and resource ('Lal Kitab analysis') and enumerates the exact report contents (Teva, Kismat & Prosperity scores, Rins, Upayas), so the agent knows precisely what it produces. However, it never distinguishes itself from the granular siblings it duplicates (astroway_vedic_lal_kitab_teva, _kismat, _prosperity, _debts, _remedies) nor from astroway_reports_generate.

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 cost block gives a real usage constraint ('5,000 credits, Tier 7, ~50% of free monthly budget — confirm with user before invoking'), which is actionable guidance. But it offers no when-to-use-this-vs-alternatives routing against the many lal_kitab and reports siblings, leaving selection to inference.

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

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

Annotations only say readOnly=false, openWorld=true, idempotent=false, destructive=false; the description adds the material facts an agent actually needs — that the call costs 5,000 credits at Tier 7, that this is roughly half a free monthly budget, and that user confirmation is required. The 'not a prophecy' disclaimer also sets expectations about the output's nature. This is genuine context beyond the structured fields.

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 prose is two compact sentences that front-load the report's content and scope, followed by clearly delimited bracketed metadata. Nothing is padded, though the disclaimer sentence is arguably low-value for tool selection.

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?

With an output schema present, the description need not explain return values, and the cost/premium warning covers the one high-stakes behavioral fact. The title signals PDF-or-HTML output but no parameter in the schema selects format, and no format explanation appears in the description — a minor gap, though not one the agent must resolve to call the tool.

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 60%, and the description only restates the single required parameter ('Required: chart'). It adds nothing about the optional fields/compact-mode, language, precision, or whitelabel parameters, all of which are documented (at varying depth) in the schema itself. Baseline 3 is appropriate when the schema carries the load.

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?

States a specific output (romantic-relationship natal report) and even names the four astrological factors it foregrounds (Venus, Mars, Moon, Descendant), which pins down what 'love report' means. An agent can distinguish this from the sibling astroway_reports_natal (general natal) and astroway_reports_synastry (two-chart relationship) reports without opening a schema.

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 premium-cost warning and the explicit instruction to 'Confirm with user before invoking' give real invocation-time guidance that a sibling-selection rule does not. It does not, however, state when to prefer this single-chart love report over astroway_reports_synastry or astroway_reports_natal, so the alternative-selection guidance is left implicit.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false), so the bar is lower. The description adds useful behavior beyond them: exact cost (5,000 credits, Tier 7, ~50% of free monthly budget), a confirmation-before-invoking instruction, and a not-investment-advice disclaimer. That is substantial value beyond the structured fields.

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 content list is front-loaded, the bracketed metadata lines are scannable, and the cost warning is visually prominent with the emoji marker. It is telegraphic and wastes little, though the opening fragment is less self-explanatory than a full sentence would be.

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-value explanation is not required. For a costly multi-param document generator the description covers purpose, required input, cost, and disclaimer, which is largely sufficient. The only real gap is routing information versus the many sibling report tools.

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?

At 60% schema coverage the schema itself already documents chart, fields, and precision in detail, so the baseline is 3. The description only restates '[Required: chart]' and adds no meaning for fields, language, precision, or whitelabel. It neither helps nor hurts relative to the schema.

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 names the resource (a financial/money natal report) and enumerates the specific content it covers (2nd house, 8th house, Jupiter, Saturn), which distinguishes it from the many other reports_* siblings by topic. The verb is carried by the title rather than the description body, and 'Financial natal:' reads as a fragment, but combined with the [Group: Reports] tag an agent can identify it.

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 gives a clear usage directive ('Confirm with user before invoking') and flags the premium cost, which is real guidance. However it names no alternative among the crowded reports_* and financial_* family, so an agent has no help choosing this over reports_natal or financial_wealth_house. Guidance is implied rather than comparative.

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

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

Annotations cover safety (readOnlyHint=false, non-destructive, non-idempotent), and the description adds material context beyond them: the premium credit cost (5,000 / Tier 7 / ~50% of free monthly budget) and the required user confirmation. It also discloses the scoring methodology and that it is a rendering operation. A minor gap is the '?format=html' query-string reference that has no matching schema parameter, which slightly muddies how the format is actually selected.

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 with the most important sentence first, then methodology, then the activity pointer and format note; the bracketed metadata stays compact. No wasted prose, though the methodology sentence is denser than strictly needed for tool selection.

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 needn't be described, and the cost/confirmation warning covers the highest-risk behavior. However, with 13 parameters at 31% schema coverage, the description leaves a genuine documentation gap for an agent trying to populate the optional inputs correctly.

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 only 31% across 13 parameters, so the description must compensate — but it only addresses `activity` (already enumerated in the schema) and gestures at the shared window-scan engine. topN, language, latitude, longitude, ayanamsaId, search_window_start/end and the whitelabel toggle are left entirely to the schema, which is thin here.

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?

States a specific verb (Render) and resource (standard A4 report of most auspicious dates for a chosen activity over a search window), and explicitly contrasts with the /vedic/muhurat/* engine family. An agent can tell this is the report-rendering variant rather than a data endpoint without opening the schema.

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?

Points to /muhurta/types for the valid activity list, notes the PDF/HTML output toggle, and the cost block instructs 'Confirm with user before invoking' — real when-to-use guidance. It stops short of an explicit when-not or a named alternative report tool, so 4 rather than 5.

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

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

Annotations only say readOnlyHint=false and non-idempotent; the description adds real behavioral context beyond them: no AI at request time, the 5000 vs 10000 credit cost of extended depth, and what whitelabel:true changes. It does not disclose rate limits or auth requirements, but the cost/behavior disclosures are substantive for a premium mutation.

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 with the primary action and outcome, and each sentence carries distinct information (contents, output switch, branding, depth/cost, language). The depth sentence is dense and slightly run-on, but there is no filler.

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, and the description covers the premium cost, required chart input, output formats and depth tiers. It does not touch the tone, length, enrich, fields or precision parameters, leaving those schema-only, which is acceptable but not fully complete for a 9-parameter premium generator.

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?

With only 44% schema description coverage, the description compensates by documenting things the schema omits: the `?format=html` output switch (absent from the schema entirely), the `language` default of uk, and the effect of `whitelabel: true` and `depth: "extended"`. It leaves tone, length, enrich, fields and precision unexplained, so it does not fully close the gap.

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?

States a specific verb+resource ('Render a Western tropical natal chart') and names the exact deliverable (single-page A4 PDF or live HTML), then enumerates the contents (Big Three, planets table with retrograde, 12 house cusps, aspects). An agent can distinguish this from render-wheel image tools and other report siblings without opening the schema.

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?

Usage context is implied through the format and depth options plus the premium-cost warning ('Confirm with user before invoking'), which is genuine guidance. However, it never names when to pick this over sibling report generators (e.g. career/love/natal-narrative reports) or when the HTML variant is preferable, so the when/when-not logic 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.

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

Adds substantial context beyond the annotations: the 5,000-credit Tier 7 cost, the ~50% free-budget consumption, and the instruction to confirm with the user. It also discloses the default format and the diffing behavior of the report. It does not cover auth needs or rate limits, so not a full 5, especially given readOnlyHint=false.

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?

Long but front-loaded, leading with scope and output format before enumerating report contents. Every clause conveys a real feature (ascendant/midheaven shift, house diffs, ACG lines, category scores). Slightly dense prose, but nothing is filler.

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 costly multi-parameter report generator it covers the essentials: required inputs, output format, cost gating, and document contents. Since an output schema is present, return values needn't be spelled out. The remaining gap is explanatory coverage of the secondary parameters (orbKm, fields, precision, categories, whitelabel, language).

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 only 38% across 8 parameters. The description maps 'places' to locations (max five) and the HTML format switch, and its mention of the 300 km line radius and 19 categories gestures at orbKm and categories, but chart, fields, precision, language, and whitelabel are left to the schema. Baseline 3 for the low coverage with partial compensation.

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?

States a specific verb and resource (compare up to five places for one birth chart) and the concrete output formats (multi-page A4 PDF by default, live HTML via ?format=html). It details the exact per-place contents, so an agent can distinguish this report generator from the geo point-lookup siblings.

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?

Gives useful triggering context (comparison across up to five relocation candidates, cost gating with 'Confirm with user before invoking'), but never names an alternative tool or states when NOT to use it versus siblings like astroway_geo_relocation or astroway_geo_acg_line_report. Usage is implied rather than routed.

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

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

Annotations only supply the safety/idempotency profile; the description adds genuinely useful behavior the annotations don't carry: fully deterministic with 0 AI, the cost of 5,000 credits (~50% of a free monthly budget), the need to confirm with the user, and the body-vs-query-string channel rule. It does not say whether the generated report is persisted (reports_history suggests it may be), which is a minor gap.

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 with the deliverable, then the options, then the cost caveat — a sensible order with no filler sentences. The long parenthetical inventory of wheel elements is slightly over-detailed relative to its decision value, but it justifies its space by telling the agent the output is high-detail.

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 6-parameter tool with a nested `chart` object and an output schema, the description covers the decision-relevant dimensions (format, style, whitelabel, i18n, cost) while the schema handles return shape and chart fields. Only the persistence/handling of the produced artifact is left unstated.

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?

With 50% schema coverage, the schema already carries the heavy lifting for `chart`, `fields`, and `precision`. The description nonetheless adds real value by mapping each `style` enum value to its visual character (editorial=light, celestial=dark+gold, classic=minimal) beyond the bare enum list, and by clarifying that `style` must be sent in the request BODY rather than the query string.

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?

States a specific verb and artifact ('Render a data-rich, print-ready natal chart poster') and then enumerates the exact contents (western wheel with element sectors, ASC arrow, placements table, balance bars, top aspects). This clearly distinguishes it from image-oriented siblings like astroway_render_wheel_western and from narrative reports. An agent knows precisely what it gets without opening the schema.

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?

Gives strong context — PDF is the default, `?format=html` returns HTML, style/whitelabel/language are the levers, and the premium cost carries an explicit 'Confirm with user before invoking' instruction. It stops short of naming alternatives (e.g. reports_natal vs. render_wheel_western), so the when-not-to-use case 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.

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

Annotations already declare the mutating, non-idempotent, open-world profile, so the bar is lower. The description adds genuinely non-structured context: the credit cost, its tier, and its share (~50%) of a free monthly budget, plus an explicit confirm-before-calling instruction. It does not mention auth or rate limits, but the premium-cost disclosure is the salient behavior for this tool.

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-loads the single high-value sentence describing output, then uses compact bracketed tags for group, endpoint, required params, and cost. Line-efficient overall, though the [Required: chart1, chart2] tag duplicates what the schema already enforces.

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?

With an output schema present the description is not obliged to describe return values, and it covers the artifact contents, cost, and required inputs. One gap: the title advertises 'PDF or HTML' but the description only mentions PDF and no format parameter exists, so output format selection is unexplained.

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 67% and the nested chart schema is exhaustively documented (formats, rejected short forms, tz handling, house-system letters). The description only restates that chart1 and chart2 are required and says nothing about fields, language, precision, or whitelabel. Baseline 3 is appropriate when the schema carries the semantics.

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?

States a specific verb ('Render') and resource ('relationship synastry PDF') and then inventories the exact contents — side-by-side Big Three, top-40 cross-chart aspect table, per-chart plus combined element/modality balance. That content spec separates it from the data-style siblings (astroway_relational_synastry*) and the narrative sibling (astroway_reports_ai_synastry_narrative).

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?

Gives one real invocation rule — 5,000 credits / Tier 7, confirm with the user first — which is a valuable cost gate. However it never says when to prefer this over astroway_reports_love, astroway_reports_generate, or the AI synastry narrative, so alternative selection 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.

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), and the description adds real behavioral context: deterministic mulberry32 RNG when seed is passed, daily seed when omitted, and upright-only cards via allowReversed=false. It also surfaces the 100-credit cost. It does not explain what the rendered output looks like or delivery method, but the output schema covers returns.

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?

Three tight sentences, front-loaded with the default spread and then the option inventory. No filler; each sentence carries usable parameter information.

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 an 8-parameter report tool with a nested whitelabel branding object and five non-schema-documented parameters, coverage is partial. The output schema removes any need to describe return values, but an agent gets no help on language, whitelabel, or compact-mode parameters.

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 only 25%, so the description must compensate, and it does for the most consequential parameter: it enumerates all ten spread values even though the schema only carries maxLength=64 with no enum. It also explains seed and allowReversed semantics. It says nothing about name, language, fields, precision, or whitelabel, leaving four parameters undocumented.

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?

States a specific verb+resource: 'Render a tarot reading PDF', and the title adds the HTML variant. This distinguishes it from the draw-only siblings (astroway_tarot_rider_waite_draw_three_card) and other report generators, though it never explicitly names an alternative.

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?

Gives defaults (three-card spread, daily seed) but no when-to-use/when-not guidance and no routing to alternatives such as the draw tools or astroway_reports_generate. The agent must infer that this is the PDF-rendering path rather than the card-drawing path.

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

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

Annotations only cover the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true). The description adds materially: the exact cost (5,000 credits, Tier 7), that it consumes ~50% of a free monthly budget, and an explicit instruction to confirm with the user before invoking — the kind of spend/operational context annotations cannot express. It still says nothing about latency or how the rendered document is returned.

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 with the core action and output content in the first sentence, then scope constraints, then a bracketed metadata block. Every line carries information, though the [Group]/[Endpoint]/[Required] block partially duplicates what the schema already declares and the endpoint string is of marginal use to an agent.

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 explained, and the description covers report contents, cost, and the required chart. What is left implicit is the delivery mechanism for the rendered document and the PDF-vs-HTML ambiguity raised by the title — small gaps against an otherwise complete brief for a premium report tool.

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 50% and the schema itself documents chart, fields, precision, and timezone in depth. The description's only real parameter contribution is the non-schema default for `year` (next calendar year when omitted) and a restatement of the required `chart`; it says nothing about language, whitelabel, or compact-mode fields/precision, so it lands at the baseline rather than compensating.

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?

Specific verb plus resource: 'Render a year-ahead transit calendar PDF grouped by month,' with content detail (Mars–Pluto aspects, the five Ptolemaic aspects, 0.5° orb) that clearly identifies this as the printable year-ahead transit report rather than the data endpoints (astroway_prognostics_transit_calendar) or the AI narrative siblings. An agent can tell what it produces without opening the schema. Minor wrinkle: the title says 'PDF or HTML' but the body says PDF only, and no format parameter exists.

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?

Usage is implied rather than stated: it is a report-generation call and the cost block warns to confirm with the user first, which is a genuine precondition. However, it never says when to prefer this over astroway_reports_ai_year_ahead_narrative, astroway_reports_ai_transit_narrative, or astroway_prognostics_transit_calendar, nor what prerequisites (e.g., an existing chart) must hold.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true and destructiveHint=false, so the write/open-world profile is covered. The description adds material context the annotations cannot: the exact credit cost (5,000, Tier 7), that it consumes roughly half a free monthly budget, and an explicit instruction to confirm with the user first. It still doesn't state the output medium (PDF vs HTML) or that repeated calls are billed again, so it stops short of a 5.

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 with the payload contents in a single dense sentence, then a compact bracketed metadata block (group, endpoint, required, cost). No filler, no repetition of the title, and the most decision-relevant fact — the premium cost warning — is placed last with a warning marker where it will be noticed.

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 explanation, and the cost/confirmation behavior is well covered. But for a premium, 5-parameter report tool sitting beside astroway_vedic_kundli and the astroway_reports_* family, the definition omits the one thing an agent most needs: how this differs from the plain Vedic kundli tool and what format it delivers. Adequate, but with a real routing gap.

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 60% and the schema itself carries rich per-field prose (timezone semantics, timezoneOffset hours, houseSystem letters, lat/lon rejection of short forms). The description contributes only '[Required: chart]' and the default 'Lahiri ayanamsa', which merely restates what the schema already documents. It adds no meaning for fields, precision, language, or whitelabel, so it sits at the baseline for partial coverage.

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 names a specific artifact (sidereal Vedic chart, Lahiri ayanamsa) and enumerates exactly what the deliverable contains: Lagna, Moon nakshatra/pada, all planet positions with nakshatra+pada+house, and a full 9-period Vimshottari Mahadasha tree. It is clear what the tool produces, but it never distinguishes itself from the sibling astroway_vedic_kundli, which by name covers the same subject matter — only the title's 'PDF or HTML' hints that this is the rendered report variant.

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 only usage guidance is the premium cost warning — '5,000 credits (Tier 7), ~50% of free monthly budget. Confirm with user before invoking' — which is genuinely useful pre-invocation advice. However, there is no routing guidance: nothing tells the agent when to pick this over astroway_vedic_kundli or the generic astroway_reports_generate. Usage context is implied by [Group: Reports] rather than stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds two things the annotations cannot: the lazy-initialization side effect ('defaults are seeded' on first access) and the explicit cost (10 credits, Tier 1). It does not mention auth scope or rate limits, keeping it short of a 5.

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 front-loaded prose sentences carry the payload, with group/endpoint/cost as compact bracketed metadata. Nothing is padded, though the cost line duplicates information an agent may also derive from the cost-estimate sibling.

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-value detail is unnecessary; the description still names the config contents. Seeding behavior and cost are covered. The only gap is routing guidance relative to the three whitelabel siblings, which no dimension besides usage covers.

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 100% and both parameters (fields, precision) are fully documented in the schema, so the baseline is 3. The description adds no meaning about compact mode, dotted paths, or precision beyond what the schema already states.

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?

States a specific verb (Read) and resource (the authenticated user's branding overrides) and enumerates the concrete fields returned (logo, palette, font, footer, custom domain). It is clearly distinct from the domain/logo/preview siblings by subject matter, though it never names those alternatives.

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 only contextual sentence is 'On first access, defaults are seeded', which is behavioral, not directional. There is no statement of when to call this versus astroway_whitelabel_preview, astroway_whitelabel_logo, or astroway_whitelabel_domain_verify, and no prerequisites or exclusions.

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

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

The description explicitly states 'Persists the result', i.e. a write/side effect, while the annotations declare readOnlyHint=true (does not modify its environment). That is a direct contradiction. The A-record fallback detail is useful, but the stated persistence behavior conflicts with the declared read-only contract.

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 compact sentences front-load the behavior and the fallback case, followed by a compact metadata block (group, endpoint, cost) with no wasted prose. Slightly dense but well ordered.

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 explained, and annotations cover the safety profile. However the description omits prerequisites (domain must first be configured via whitelabel_config) and does not clarify what persisting the result affects, which matters for a verification tool that claims to write state.

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 100%, so both generic response-shaping params (fields, precision) are already fully documented in the schema. The description adds no parameter-level meaning of its own, so the baseline 3 applies.

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 specific verb and resource ('Check whether the configured custom_domain points to api.astroway.info via CNAME') and even names the exact expected target, so an agent can tell immediately what the call does. It is cleanly separable from the other whitelabel siblings (config/logo/preview), none of which overlap with DNS verification.

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 implies the right moment ('the configured custom_domain', i.e. after setup) and explains the A-record fallback outcome, but never explicitly says when to use this versus astroway_whitelabel_config or after which setup step, and gives no prerequisites or when-not guidance.

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

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

The description reports a mutating, destructive behavior: it 'Replaces any prior logo and deletes the old file from storage'. The annotations declare readOnlyHint=true and destructiveHint=false, which directly contradicts that. Per the rubric this is an annotation contradiction and scores 1, even though the description itself is the more informative half.

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?

Three tight sentences with the action front-loaded, followed by a scannable metadata block. Slight redundancy: the `data:image/<png|jpeg|svg+xml|webp>` enumeration restates the schema's pattern, and the bracketed metadata is boilerplate rather than description content.

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 explanation, and the key mutation facts (overwrite + delete of the prior file, size cap, 10-credit Tier 1 cost) are disclosed. Still missing for a 3-parameter write tool: permission/auth requirements and any explanation of the two undocumented compaction parameters.

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 67%, so the schema carries part of the load. The description does add real meaning for the required data_url beyond the regex (the 512 KB limit, the readable format list), but it says nothing about `fields` and `precision`, which look like copy-pasted compaction parameters with no stated role in a logo upload.

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?

States a specific verb and resource ('Upload a logo') plus the accepted format, the 512 KB ceiling, and the overwrite semantics. Among the white-label siblings (astroway_whitelabel_config, astroway_whitelabel_domain_verify, astroway_whitelabel_preview) an agent can tell immediately that this one sets the brand mark rather than configuring or previewing it.

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?

Usage is only implied: the [Group: White-label] and [Endpoint: POST /v1/whitelabel/logo] metadata make the context clear, but there is no explicit when-to-use, no statement of prerequisites (must the white-label be configured or the domain verified first?), and no routing to or away from the sibling whitelabel tools.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds genuinely new behavioural facts they cannot express: the 5,000-credit Tier 7 price, its magnitude (~50% of the free monthly budget), a user-confirmation requirement, the POST endpoint, and the dependency on the authenticated user's stored white-label config.

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?

Three tightly written sentences: the render action and theming source come first, the chart/fallback fork second, cost metadata last. The cost warning is bolded and front-loaded in its own block so an agent cannot miss the budget impact. No filler sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.