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

Adds context beyond the annotations: the call is free, and a profile matching an existing name is returned rather than duplicated — this makes the idempotentHint concrete and tells the agent a duplicate is not an error. It also imposes a content constraint (use only what the user said; never invent credentials, experiences or opinions), which is real behavioral guidance. It doesn't cover whether the profile can later be edited or deleted.

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?

Front-loaded with the core definition and an example, then the constraint and the downstream hand-off. Dense but mostly earning its words; the "Free." fragment and the chained final sentence slightly interrupt flow.

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 still explains what comes back (a profile, reused on name collision) and how to consume the returned id. For a 7-parameter creation tool with full schema coverage and beneficial annotations, this is nearly complete; only lifecycle facts (editing/removing a profile) are absent.

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 would be 3, but the description adds meaning the schema does not: `name` acts as a deduplication key, so the agent knows a repeat name yields the existing profile instead of a new one. It also frames the purpose field conceptually (who is speaking) without restating the schema text.

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 ("Add someone a brand posts as") and disambiguates the concept with a concrete example of the founder posting on LinkedIn in first person. An agent can separate this from list_publishing_profiles and suggest_publishing_profiles without opening a schema.

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 downstream routing: the returned id is passed as `persona_id` to create_content_pack, which tells the agent what this tool feeds into. It does not state when to prefer suggest_publishing_profiles or list_publishing_profiles first (e.g. to avoid duplicates proactively), so an exclusion is missing.

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