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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful non-annotated context: the operation costs 1 credit and custom domains are accepted as input. It does not cover caching behavior implied by cache_max_age or why a 'rounded' subscriber badge matters (precision loss in the returned data).

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 short sentences, front-loaded with the resource type and the returned field list. The leading fragment 'Publication.' duplicates the title, but the remaining content is dense and every clause carries information.

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 field enumeration in the description is what tells an agent what comes back, and it does that adequately. The main residual gaps are the undocumented cache_max_age parameter and the absence of any cue separating this from substack_profile.

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 50%: the `publication` parameter is well documented in-schema, while `cache_max_age` has no description anywhere. The description usefully reinforces that custom domains are accepted, which expands acceptable input formats beyond the schema's examples, but it says nothing to compensate for the undocumented cache_max_age parameter.

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 description clearly identifies the resource as a Substack publication and enumerates the returned fields (name, description, author, custom domain, paid plans, subscriber badge), which makes the retrieval purpose concrete. It lacks an explicit verb and never distinguishes itself from the close sibling substack_profile, so an agent cannot tell from the description alone which one fetches publication-level data.

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?

There is no statement of when to use this tool, no exclusions, and no reference to any of the four Substack siblings (substack_profile, substack_post, substack_posts, substack_comments). The only usage-adjacent remark is the cost note, which is not guidance about tool selection.

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