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

Annotations only cover safety (readOnlyHint, non-destructive, closed-world); the description adds behavior they don't: 'Never bills and returns catalog metadata only', which is critical for an agent worried about cost. It also explains the distinct return shapes per call mode (compact indexes vs. full fields[] rows) and the composability constraint on scopes.

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?

Purpose and usage are front-loaded, which is good, but the middle bloats into per-tool fieldset inventories ('Standard contains 19 available ids and All contains 24...', 'seven fieldsets register 94 available ids') that are exactly the data this tool returns and will go stale. Those counts don't help an agent select or invoke the tool, so a meaningful share of the text doesn't earn 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, the description steps up and describes return shapes: compact fieldsets[]/groups[]/upgrade_field_ids[] with tool only, and MCP-shaped fields[] with id, group, title, short_title, description, included when scopes are added. It also notes the Summary tool takes no fields argument and that unavailable ids appear with included=unavailable, so an agent knows what to expect from every call mode.

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 0%, so the description must carry the params, and it largely does: tool is required with nine supported values, fieldset accepts Standard or All, groups and field_ids compose, and 'Fieldset cannot combine with other scopes' documents a real cross-parameter constraint. The query parameter, however, gets only a passing mention and its matching/filtering behavior is never explained, leaving one 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 opening states a specific verb and resource: 'Discover exact output field ids for a consuming MCP record tool', immediately separating this catalog tool from the record tools it describes. It reinforces the distinction by naming sibling tools (get_property_persons, get_criteria) that should be used for other jobs. An agent can tell at a glance that this is a metadata lookup, not a data-fetch 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 explicit when-to-use ('Discover exact output field ids'), when-to-scope (add groups, field_ids, or query for full MCP-shaped rows), and when-not-to-use ('Do not call this tool to identify the owner; use get_property_persons... Use get_criteria for search filters'). It also enumerates the nine supported consuming tools and warns that 'Other consuming tools are unsupported'.

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