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

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses the concrete effect: every row becomes or matches a contact tagged 'Substack subscriber' with plan and status, which implies dedupe-merge behavior. It does not warn about the destructive implication of merging rows into existing contacts or how conflicts/duplicates are resolved, which matters given destructiveHint=true.

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?

Three sentences, each carrying a distinct load: what the import produces, how to resolve the file, and how to resolve the publication. The core action is front-loaded with no filler.

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?

Covers source identification, file resolution, publication requirement, and the resulting contact tagging, which is what an agent needs to invoke it correctly on a 3-parameter mutation tool with no output schema. What is missing is any indication of the result shape (counts imported vs matched, error behavior on bad rows).

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%, so baseline is 3, but the description adds operational meaning: object_id comes from search_graph_objects, name is the fallback when object_id is unknown, and publication is defined as the subdomain before .substack.com with an instruction to ask if missing. This clarifies the relationship between the two file-locating parameters rather than just repeating them.

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?

States a specific verb and resource ('Import a Substack subscriber export') and names the source (the CSV from the Subscribers page), which is far more than the title restates. It also distinguishes itself from the read-side siblings by describing the file-discovery path via search_graph_objects. It does not explicitly distinguish itself from the similarly-named import_contacts_from_file sibling.

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 clear when-to-use context (the user uploaded a Substack CSV) plus the prerequisite workflow: locate the file with search_graph_objects and pass object_id, or use name as a fallback. It also says to ask the user if the publication subdomain is unknown. No explicit exclusions or when-not guidance are given.

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