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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety and idempotence are covered. The description adds valuable behavioral context beyond annotations: it describes the provenance token mechanism, the 15-minute window, cross-replica behavior, the requirement to map source_path, and the data accuracy contract with derived metrics labeling. It also mandates ending with an attribution footer. These are substantial non-obvious behaviors. It does not describe return format or pagination, but that is acceptable given no output schema and annotations covering the safety profile.

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 quite long and mixes core tool functionality with tangential instructions about chart_render, provenance tokens, attribution footers, and a data accuracy contract. While these are important, they are not front-loaded relative to core purpose; the first sentence is good, but the rest is a block of policy text that might be better placed elsewhere. It is not concise and could be structured with headings or shorter sentences.

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?

Given the tool has 2 parameters (object with action enum and params object) and 100% schema coverage, plus annotations covering safety, the description is relatively complete for calling the tool. However, it lacks any mention of rate limits, authentication requirements (though the schema mentions a connected Notion token), or what happens on error. The extensive provenance and data accuracy contract add context but are not directly about invoking this tool; they are about downstream chart_render behavior. Overall, it is adequate but has gaps in operational transparency.

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 itself enumerates all actions and their parameters in detail, including per-action parameter lists. The description adds no additional parameter semantics beyond what the schema provides (e.g., it does not explain the 'params' object structure, the 'projection' parameter, or the meaning of 'filter_object'). With schema coverage high, baseline is 3.

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 two sentences clearly state the resource (Notion workspace) and the verbs (read pages, databases, blocks, users; search; query; traverse). It distinguishes itself from other connectors by naming the Notion domain explicitly. However, it does not differentiate itself from sibling connectors in terms of when a Notion tool should be chosen over, say, a generic file connector. The action enum itself is defined only in the schema, not in the description.

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 almost no guidance on when to use this connector versus alternatives. It mentions calling chart_render for visuals, which is a downstream usage hint, but does not tell the agent when to select notion_connector over other connectors (e.g., for collaborative docs vs. code). There are no explicit when-not-to-use conditions or alternative tool recommendations for the core read operations.

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