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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety is covered by structured fields. The description adds genuinely non-obvious behavior beyond them: the rule set is SHARED per project + taxonomy_code + locale, meaning every feed on that taxonomy observes the same rules. That sharing/auth-free read semantics go beyond the annotations, though there is no mention of rate limits or permissions.

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 front-loaded with the purpose, then addressing modes, then the return shape, then sibling routing — a logical order with dense information. It loses a point for mild redundancy, since the second sentence largely restates the first, and for cramming the sibling guidance into the tail end.

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 supplies the return shape inline ({taxonomyCode, taxonomyLocale, rules:[...], total}) including the rule fields, and it explains both addressing paths plus the optional project_id. For a four-parameter read tool this covers everything an agent needs to call it correctly and interpret the result.

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% — feed_id and project_id have no schema descriptions — but the description compensates by explaining that feed_id addresses the taxonomy implicitly, that taxonomy_code is the explicit alternative with optional taxonomy_locale, and that project_id is OPTIONAL and inferred for single-project customers. That is meaningful semantics the schema does not supply, though it does not state behavior when both feed_id and taxonomy_code are given.

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 first sentence names a specific verb and resource — reading the current category-mapping rules for a taxonomy — and defines the store→marketplace/taxonomy direction. It is clearly distinguishable from siblings such as set_category_mapping (write), list_unmapped_categories (gap finding), and search_target_categories (target lookup), all of which are named in the text.

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 explicitly routes the agent: use this to read existing mappings, then use list_unmapped_categories to find gaps, search_target_categories to find a target, and set_category_mapping to fill them. It also states the two mutually exclusive addressing modes (feed_id OR taxonomy_code + optional taxonomy_locale), so the caller knows which parameter shape selects which behavior.

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