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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds value beyond them by describing the shape of what comes back: pages nested in groups, page handles usable in read_doc, plus sections.

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 sentence with no filler, and the core action ('Lists every page') is front-loaded. The trailing clause about page names and sections is dense but each element carries 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 a zero-required-parameter read tool with no output schema, the description conveys enough to call it and roughly what comes back. It does not address volume or pagination for a full enumeration, nor how the optional source filter interacts with 'every page'.

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 'source' parameter is documented with its enum in the schema, so the baseline is 3. The description adds nothing about filtering and its 'every page' wording slightly obscures that the optional source parameter narrows the listing.

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 (lists) and resource (every page of Anahita's docs) and sketches the response structure (groups, page names, sections). It also names read_doc, making the relationship to that sibling explicit rather than tautological.

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 mention of 'each page's name for read_doc' hints that this is the discovery step before reading, but there is no explicit when-to-use or when-not, and no routing against search_docs, which is the obvious alternative for targeted lookups.

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, closed-world and non-destructive, so safety is covered. The description adds genuinely new behavioral information: the response shape changes depending on arguments (grouped services, a service's routes, or word-matching routes). It does not clarify what happens when both arguments are supplied, which is the main remaining behavioral 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?

One dense sentence with no filler, and the base case (grouped services) is front-loaded before the narrowing modes. The semicolon-chained clauses are compact but slightly harder to parse than separate sentences 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?

With no output schema, the description carries the burden of describing returns; it partially does so (groups, routes, matches) but not the structure or pagination. The unstated precedence when both query and service are provided leaves an agent guessing.

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 individual parameter meaning is already documented. The description still adds interaction semantics the schema does not state: service narrows to that service's routes, query selects matching routes, and with neither you get grouped services.

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 ('Lists the API's services in their groups') and describes the three result shapes. It distinguishes itself reasonably from siblings like read_endpoint and read_shape by covering the enumeration case, though it never names those siblings 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 'with a service... with words...' phrasing implies how to pick a mode, but there is no explicit when-to-use guidance or reference to alternatives such as read_endpoint for fetching a single route. Usage must be inferred from parameter descriptions.

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 establish that this is a safe, idempotent read operation, so the description is not required to explain safety. It does add useful behavior beyond the annotations: output is Markdown, and selecting a section includes the sections beneath it. It leaves out error behavior for missing pages or sections and any size limits.

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 a single front-loaded sentence with no wasted words. It states the core action and the main variant immediately.

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 the read-only annotations, complete parameter schema, and no output schema, the definition is mostly complete. However, it does not say what happens when a page or section is missing, whether large pages are truncated, or how section paths are matched.

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 baseline would be 3. The description exceeds that by clarifying what the section parameter does: it returns that section together with the sections under it, which the schema does not state.

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: it reads one page of the docs as Markdown, or a section of that page. This clearly separates it from list_docs and search_docs, though it does not explicitly distinguish it from read_endpoint or read_shape.

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 by the contrast between reading a whole page and reading a section, but there is no explicit guidance on when to use this instead of list_docs or search_docs. The agent must infer the selection criteria.

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 that the result is a complete view of a single route (permissions, params, body, all responses), but says nothing about behavior for unknown methods/paths or how exact the match must be.

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?

A single front-loaded sentence that enumerates the returned content without filler. It is efficient, though the enumeration is doing double duty as both scope and return-value summary.

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 rightly sketches what comes back (permissions, parameters/body, responses), and both required params are fully specified in the schema. Only the mismatch/not-found behavior is unaddressed, a minor gap for a two-parameter read 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 100%, so both method and path are already documented, including the literal-vs-template path forms. The description adds no formatting or matching semantics beyond the schema baseline.

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 ('Reads one API route in full') and enumerates the retrieval contents: permissions, parameters/body, and responses. This makes it clearly distinct from list_endpoints and read_doc, though it never names a sibling to sharpen the 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 is only implied: 'one ... in full' hints at the detail counterpart to list_endpoints, but the description never says when to prefer this over list_endpoints, read_doc, or read_shape, nor any prerequisites.

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 fully covered structurally. The description adds only that fields are included in the result; it says nothing about failure behavior for unknown shape names or result size, which would have been the value-add.

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 with the verb and resource first, then the clarifying parenthetical. No filler, though the parenthetical is slightly dense compared to splitting the 'fields' detail 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 one-parameter read tool with rich annotations, the description is adequate but thin: it does not state how shape names are discovered (only the schema hints at read_endpoint), nor what the returned structure looks like beyond 'its fields'. No output schema exists, so a one-line return description carries that burden loosely.

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 parameter already documents that 'name' is a shape such as "Refusal" as read_endpoint names it. The description adds no further naming, casing, or format guidance 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 (read) and resource (one API shape) and defines what a shape is ('a schema a route takes or answers with') plus what is returned ('its fields'). It does not explicitly distinguish itself from siblings like read_endpoint, though the concept is differentiated by the parenthetical.

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 reader infers this is the lookup to use once a shape name is known (e.g., from read_endpoint). There is no explicit when-to-use, no exclusions, and no statement of what to do if the shape name is unknown or ambiguous.

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 already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new behavioral context: results are ranked by relevance ("best sections first") and each hit carries a page, a section, and a snippet line — enough to know the response shape without an output schema.

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?

A single front-loaded sentence that leads with the verb and resource, then immediately describes the return shape. No filler, no restatement of the 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?

The three parameters are fully documented in the schema and the description covers the response shape, which is enough to invoke it correctly. What is missing is routing context — the sibling set includes list_docs and read_doc, and the description never explains when a search is better than browsing or fetching a known page, nor what happens when there are no matches.

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 query, limit, and source are fully self-documenting; baseline 3 applies. The description adds only that matching is on "words" — it does not clarify ranking interaction with limit or what source filtering does beyond the enum descriptions.

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?

"Searches Anahita's docs by words" gives a specific verb and resource, and the clause about returning the best sections first with page/section/snippet tells the agent what comes back. It is distinct from list_docs and read_doc by implication of ranked keyword retrieval, though it never names those siblings 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?

Usage is only implied: the word "Searches" and "by words" signal keyword lookup rather than browsing or full reads, which the schema's query examples reinforce. There is no explicit statement of when to prefer this over list_docs or read_doc, and no exclusions.

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