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

Annotations already cover read-only, idempotent, and non-destructive behavior, but the description adds valuable context: it informs the agent that chart_render labels values as 'unverified_model_data', it mandates a response suffix ('Powered by CorpusIQ'), and it establishes a strict data accuracy contract (only trust returned fields, mark derived metrics, handle missing data). This goes beyond annotations to define how the agent should behave with the tool's 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?

The description is longer than strictly necessary, but it's structured logically: a concise purpose statement followed by essential integration rules (when to call chart_render, response suffix, data accuracy). Every sentence serves a purpose, though it could theoretically be condensed. It's front-loaded with the core function, and the additional instructions are clearly separated, making it easy to parse.

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 multi-action connector with no output schema, the description provides sufficient context for correct invocation: it explains data handling, when to delegate to chart_render, and the required response format. It doesn't detail the return structure, but the schema's action descriptions cover that. Together with annotations, an agent has enough information to use the tool safely and 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?

The input schema covers 100% of parameters with descriptions for each action and the params object layout. The description does not add new parameter-level semantics; it just references the general capabilities. Since the schema fully documents parameters, the baseline of 3 applies. The description doesn't repeat or enhance the schema, so no higher score.

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 states specific actions ('browse, search, and retrieve') on a clear resource ('Airtable bases, tables, and records'). It differentiates from chart_render by explicitly directing when to use that tool for visualizations, and the data accuracy contract clarifies the scope of what this tool returns versus what must not be inferred. This is a clear, distinct purpose that an agent can immediately grasp.

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 explicit guidance on when to call chart_render instead ('When the user asks for a visual, trend, comparison, or recap') and provides a detailed data accuracy contract for how to handle returned data. It doesn't explicitly compare this tool to other connectors, but the Airtable-specific scope is evident from the name and description. The guidance on when not to invent data is a strong usage boundary.

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