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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds genuinely useful behavior — that traversal is recursive into nested subcategories — but says nothing about result size, depth limits, or pagination for large trees, which matters for a recursive enumeration.

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 no filler; the verb and the return contents come first. Slightly dense with the trailing "including nested subcategories" clause, but 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?

A one-parameter read tool with an output schema and full param coverage needs little more than this. The main omission is any hint about scale or depth of the recursive listing, which would help an agent decide whether to browse or search.

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 parameter already carries example paths ("forms", "forms/field-types"). The description adds no path syntax, root/empty-string convention, or error behavior beyond what the schema states, 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 concrete verb and resource ("Browse a category") and specifies the payload: subcategory paths plus every article, including nested ones. That recursion detail is what distinguishes it from a flat catalog lister like list_categories, though no sibling is named 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 implied rather than stated — the agent can infer it should call this to enumerate a category's contents, but the description never says when to prefer it over search_docs, list_docs, list_categories, or get_doc_structure, nor does it state 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 and idempotentHint, so the safety profile is covered. The description adds real value beyond that by disclosing that the data is a local copy with a measurable age, which tells the agent results elsewhere may be stale and that this call is a cheap status probe.

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, front-loaded with the verb and resource, then the returned fields in a compact list. No filler and nothing that could be cut.

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 parameters, an output schema, and read-only annotations, the description covers what an agent needs to decide to call it. It stops short of explaining how the staleness figure should influence other operations, which would be the last useful detail for a corpus-status 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 tool takes zero parameters, so the baseline applies and there is nothing for the schema to under-document. The description correctly implies a single global, unfiltered query over the whole corpus.

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 a specific verb ('Report') and resource ('corpus metadata') and enumerates exactly what is returned: article count, categories, last sync, and local-copy age. That clearly separates it from the read/search siblings, though the mention of 'categories' creates mild overlap with list_categories that is not explicitly disambiguated.

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: reporting local-copy age hints at a staleness check before or after searching, but the description never states when to call this versus list_categories or list_docs, nor any exclusions. An agent can infer the intent but is given no routing 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 and idempotentHint=true, so the safety profile is covered. The description adds that the payload is a heading/anchor listing rather than body content, but does not disclose ordering, hierarchy depth, or whether anchor identifiers are callable elsewhere; an output schema exists, so return-format detail is not required.

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 object of the operation (heading/anchor TOC) is front-loaded after the verb. It is efficient, though the extreme brevity leaves the guidance gaps noted above.

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 simple one-parameter read tool with full schema coverage, an output schema, and safety annotations, the description covers the essentials. It is still thin on how the TOC relates to the read_doc/read_doc_section workflow, which is the main thing an agent needs to sequence calls 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 coverage is 100% and the single `doc` parameter is documented as "Article id or unique slug," so the schema carries parameter meaning. The description only adds that a single article is targeted ("one article"), which is marginal beyond that 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?

"Show the heading/anchor table of contents for one article" names a specific resource (headings/anchors TOC) and a clear read verb, which distinguishes it in spirit from read_doc and read_doc_section. It stops short of explicitly naming those siblings, so the differentiation must be inferred from the word "structure."

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: nothing says to call this first to find anchors before fetching a section with read_doc_section, nor any exclusions. The agent must infer the navigation use case from the phrase "table of contents" alone.

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 readOnlyHint=true and idempotentHint=true, so the safety profile is covered without description help. The description adds that results are exhaustive ('every') and that counts are included, which is useful context about result shape. It says nothing about ordering, depth of paths, or what an empty result means, so it earns a middling score rather than a high one.

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 sentence that front-loads the scope ('every documentation category path') and appends the one piece of payload detail that matters ('with article counts'). There is no filler, hedging, or restatement of the tool name.

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 zero parameters, full schema coverage, and an output schema that documents the return shape, the definition is nearly self-sufficient; the description need not explain the response format. The only real gap is the lack of differentiation from browse_docs_by_category, which the sibling list shows is a live ambiguity risk.

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 tool takes zero parameters, which is the baseline-4 case; there is nothing to disambiguate and no schema gap to compensate for. The description correctly signals that no filtering input is accepted by emphasizing 'every'.

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 a specific verb ('List'), a specific resource ('every documentation category path'), and even the payload shape ('with article counts'), so the agent knows exactly what comes back. It does not name or contrast with the closely related sibling browse_docs_by_category, so the boundary between the two must be inferred.

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: an agent can guess this is the discovery call to run before browsing or reading docs, and 'every ... path' hints at a full unfiltered enumeration. There is no explicit when-to-use, no when-not-to-use, and no mention of browse_docs_by_category as the alternative for drilling into a single category.

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 and idempotentHint, so the safety profile is covered. The description adds only that category filtering is optional, and says nothing about whether the full corpus is returned, ordering, or result size limits — behavior an agent might care about for a list operation.

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 with no filler or redundancy. It is arguably over-terse given the crowded sibling set, but nothing in it 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?

With one optional parameter, full schema coverage, an output schema, and safety annotations, the description covers what the agent minimally needs to invoke it. The remaining gap is routing guidance against the several similar listing/search 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?

Schema coverage is 100% and the schema's own description supplies the format example ('add-ons/ecommerce'). The description only echoes that the category filter is optional, adding no meaning beyond the schema, 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 names a specific verb and resource ('List documentation articles') plus the filtering scope, so the agent knows exactly what the tool returns. It does not distinguish itself from the closely related siblings search_docs and browse_docs_by_category, which is the main clarity gap.

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 choose this tool over search_docs, browse_docs_by_category, or list_categories, all of which plausibly overlap. 'Optionally filtered by category path' hints at the filter's use, but nothing tells the agent when the unfiltered list is the right call versus a search.

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 and idempotentHint, so the safety profile is covered; the description adds the genuinely useful behavioral detail that articles can exceed 30,000 tokens, which is a real context-cost warning. It says nothing about truncation, pagination, or linked-section behavior, which is the main residual 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?

Two sentences, no filler, and the core action is front-loaded ahead of the cost caveat and the alternative. Every clause 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?

For a single-parameter read tool with an output schema and read-only annotations, this is close to sufficient: purpose, cost warning, and alternative path are all present. Only the missing guidance on when a full read is unavoidable keeps it short of full marks.

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 description coverage at 100% and only one parameter, the schema already explains that `doc` accepts an id or unique slug. The description adds no format examples, no slug-versus-id distinction, and no error behavior for unknown ids, so it neither helps nor hurts 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?

"Read a complete documentation article" gives a specific verb and resource, and the word "complete" implicitly separates it from the sibling read_doc_section, which fetches only part. An agent can pick between the two without opening either 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?

It names concrete alternatives (search_docs + read_doc_section) and the condition favoring them (large articles). The qualifier "when possible" is loose, though – it never states the case where a full read is actually required, so the routing rule is suggestive rather than decisive.

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 and idempotentHint, and the description adds genuinely new behavioral context by stating the expected output size ('a few hundred tokens'), which helps with budgeting and batching decisions. It does not cover failure modes such as a missing section or an ambiguous heading prefix, which is a minor gap against the annotations already in place.

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 short sentences with zero filler, and the scoping statement is front-loaded ahead of the sibling comparison. Every clause 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?

With an output schema present, a fully covered parameter schema, and safety annotations, the description covers what an agent needs to select and invoke it. The only meaningful omission is what happens when the section identifier does not resolve.

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 both parameters are already fully documented in the schema, including the anchor/heading/prefix forms. The description only echoes 'anchor or heading' and adds no syntax or disambiguation detail beyond that 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 ('Read one section of a documentation article') with an explicit scoping mechanism ('by anchor or heading'), which makes it immediately distinguishable from the sibling read_doc, which returns a whole article.

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 names the preferred alternative ('Prefer this over read_doc') and justifies it with a token-cost rationale. It lacks an explicit when-to-use-read_doc-instead clause, but the implied inverse (need the whole article) is easy to infer.

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 and idempotentHint, so the safety profile is covered. The description adds real behavioral context beyond that: results are ranked sections with only a snippet, not full content, and a second call is required to get the full section — which shapes how an agent should consume the output.

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 with zero filler, front-loaded with the purpose and followed by result shape and the natural next step. Every sentence earns its place.

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

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

An output schema exists and all three parameters are documented, so the description need not explain return values; what it does explain is the snippet-to-full-section handoff. Minor gap: no mention of empty-result behavior or whether the query is keyword vs natural-language matching.

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 (1-25, default 5), and category path are already fully documented in the schema. The description adds no extra meaning about parameter interplay (e.g. how category narrows ranking or what happens when no sections match), 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 Formidable Forms documentation") plus the granularity of results (ranked sections with snippet, heading, anchor, doc id). The final sentence distinguishes it from read_doc_section, so an agent can tell the search tool apart from the read/list siblings without opening any 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 description gives a clear two-step workflow: search here, then pass doc id + anchor to read_doc_section for full content. It does not explicitly say when to prefer list_docs / browse_docs_by_category / get_doc_structure over searching, so the alternative-selection guidance is implied 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 this is a non-read-only, open-world, idempotent, non-destructive operation, so the safety bar is partly covered. The description adds the valuable incremental-sync rule (only changed last-modified timestamps), but omits what happens to locally stored articles that were removed upstream, whether local edits are overwritten, and how long or how costly the fetch is.

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 short sentences, zero filler, with the core action stated first and the default-vs-force contrast immediately after. Nothing could be removed without losing meaning.

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 only two optional parameters, full schema coverage, an output schema, and annotations, the description covers what an agent needs to decide and call correctly. The remaining gap is downstream effects on the local corpus, which matters for a mutation tool but is a modest omission given the annotation coverage.

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 is 3, and the description does reinforce the meaning of force=true as a full refetch. It adds no information about the limit parameter, but the schema already explains that one adequately.

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 a specific verb and resource — 'Refresh the documentation corpus from formidableforms.com' — which clearly separates this ingest/sync tool from the read-oriented siblings (search_docs, read_doc, list_docs). It stops short of naming any sibling explicitly, but the write/refresh nature is unmistakable.

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 states the default incremental behavior and the condition that overrides it ('unless force=true'), which is useful decision guidance for the force flag. However, it never says when an agent should invoke a refresh at all versus just reading existing docs, nor any prerequisite such as needing a stale corpus first.

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