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

The description reveals behavior well beyond the readOnlyHint/destructiveHint annotations: it explains that the tool reads a generated file, returns deterministic findings, gates real sample data behind a user-approval flow (acknowledge_sensitive), returns an empty sensitiveGate on first call, and exposes a file_missing status. It also describes paging by offset. This is rich behavioral context with no annotation contradiction.

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 long, but every sentence carries operational value: purpose, input semantics, output shape, sensitive-data gate, paging, and next-step fixes. It is front-loaded with the core purpose before parameter details. It could be tightened slightly (e.g., the sensitive-gate flow is repeated twice), but given the complexity of 6 parameters and a multi-step approval workflow, the length is justified.

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 specifying return fields (missingSource, emptyInOutput, specViolations), the spec and sample structure, the status enum values, and the sensitiveGate shape. It also covers the full call sequence (first call, user approval, re-call with acknowledge_sensitive) and the post-processing responsibilities of the agent. Nothing an agent needs to call and interpret the tool 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?

The schema covers 67% of parameters, but the description adds meaning for the two undocumented ones: feed_id (sourced from list_feeds / create_feed) and project_id (optional vs required based on multi-project customers, with a pointer to list_projects). It also enriches acknowledge_sensitive (first-call gate vs actual values) and offset (page by increasing offset in steps of sample_size), going beyond the schema text. A small deduction because response_format is not explained in the description, though the schema covers it.

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 sentence is explicit: 'File-level check of a feed's attribute mapping (reads the generated feed file).' It names a specific verb (verify), a specific resource (feed attribute mapping), and the mechanism (reads the generated feed file), which distinguishes it from sibling tools like get_feed or get_feed_status that have different purposes.

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 provides clear usage context: it must be run against a generated feed file, and it tells the agent when to call list_projects ('project_id_required if they have several, then call list_projects'). It also gives a follow-up workflow ('To fix findings: map_feed_attribute for each, then export_feed, then re-run this tool'), which implies when this tool is the right verification step. It does not explicitly state when to prefer an alternative like get_feed, so it loses a point.

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