AstroWay API Docs

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond that: the complete 770-operation coverage and the fact that no API key is needed, which is a non-obvious access trait an agent would otherwise have to discover by failing.

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 dense sentences with zero filler; the return-value payload is front-loaded and the access caveat follows. Every clause adds information an agent can act on.

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?

There is no output schema, but the description compensates by enumerating the returned fields (method, URL, credit cost, required body fields, reference link). Combined with full schema coverage and safety annotations, nothing an agent needs to invoke this correctly is missing.

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 all three parameters (query, limit, keyless_only) are already documented with examples and defaults. The description's mention of keyless operation loosely relates to keyless_only but adds no syntax or semantics beyond the schema. Baseline 3 is appropriate when the schema carries the burden.

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 (Find) and resource (endpoints) and immediately enumerates what each result carries: method, URL, credit cost, required body fields, and reference link. This is clearly distinguishable from the sibling docs tools (list_docs, read_doc, search_docs), which operate on documentation rather than operations.

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 real usage context: it covers all 770 operations and requires no API key, so an agent knows it can be used to price a workflow before credentials exist. It does not explicitly name alternatives or state when-not to use it, but the scope statement is strong enough to route correctly.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds the useful structural fact that results are grouped by section, but says nothing about result size, pagination, or language fallback behavior.

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 tight sentences, front-loaded with what the tool returns, followed immediately by the routing hint. Every clause earns its place.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and only one optional enumerated parameter, the description adequately conveys the shape of the result (whole index, sectioned) and its role relative to find_endpoint. A note on result volume or ordering would close the remaining 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 coverage is 100% and the single 'lang' parameter is fully documented in the schema, including the enum and default. The description adds no additional semantics about language selection, 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?

States precisely what is returned (the whole guide index, grouped by section) and contrasts it with find_endpoint's subject-based API reference. It only implicitly signals its relation to search_docs ('before searching for it'), so sibling differentiation is strong but not complete.

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 clear use case ('see what exists before searching') and an explicit pairing instruction with find_endpoint, and rules the API reference out of this tool. No explicit negative case (e.g. when not to use it vs read_doc) is given.

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). The description adds value beyond them by disclosing the return format (markdown) and the index-membership restriction on valid inputs.

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 short sentences, zero waste, front-loaded with the action and output format before the input-origin and constraint details.

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 single-param read tool with no output schema, the description covers action, output format (markdown), how to obtain the required input, and the validity constraint. Nothing needed to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns above it by tying the url value to its origin ('the url that search_docs printed'), clarifying the expected path format beyond the schema's example strings.

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 with output format: 'Fetch one guide as markdown.' It distinguishes itself from search_docs by requiring a single page url, but does not contrast with list_docs or find_endpoint, leaving sibling differentiation partly 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?

Gives a clear prerequisite workflow: take the url that search_docs printed, and notes 'Only pages in the index can be read' as an eligibility constraint. It stops short of naming when NOT to use this tool or which sibling to pick for other needs.

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 and closed-world, so the safety profile is covered. The description adds value beyond them by disclosing the return shape (title, URL, section list, read_doc argument) and the auth requirement ("No API key needed"), which is meaningful operational context for an agent.

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 short sentences, front-loaded with the core action and scope, then the return shape, then the routing rule. Every sentence carries distinct information; there is no filler or restatement of the name/title.

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 no output schema, the description compensates by describing the returned fields and the downstream argument for read_doc. Combined with 100% schema coverage and rich annotations, an agent has everything needed to select and invoke the tool 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 100%, so language, limit and query are already fully documented in the schema, including the enum values and defaults. The description adds no parameter-level detail (no hint about syntax, quoting, or which language setting to prefer), 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?

States a specific verb and resource ("Search the AstroWay guides") and enumerates the covered content domains (authentication, credits, error codes, field formats, agent setup, product pages), which lets an agent tell it apart from sibling tools without opening a schema. It also explicitly names the sibling it is not, find_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?

Gives an explicit negative condition plus the alternative: "For 'which endpoint do I call' use find_endpoint instead, which also gives the price." That is a concrete when-not-to-use rule with a named replacement, which is exactly what routing requires.

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