Relationship ledger (CRM): who engages with you, and who to follow back

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

The description goes beyond the annotation hints by explaining the local persistence model, what data is tracked, that note/tag memory persists into the next session, and the side effect of queue=true creating handoff(follow) items. It does not describe return values, auth limits, or rate limits, but it is not misleading and does not contradict the annotations.

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 dense but scannable, using a clear lead-in and a short bullet-style breakdown of actions. Every sentence adds operational value such as weight formulas, persistence behavior, and the scout pairing; there is no filler or repetition of schema declarations.

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 tool with no output schema, the description is strong enough to guide action selection and provide useful mental models for invite: list valuation, the note/tag persistence, and the handoff-queue side effect. The main completeness gap is the absence of precise filter-band semantics and what the returned records contain per action.

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 description adds strong meaning for the action values, especially the top scoring formula and suggest_follows trigger rule. However, with only 33% schema description coverage, meaningful gaps remain: limit is not explained, and the filter enum values such as peer_small, mid, and large have no threshold definitions.

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 title immediately frames this as a relationship ledger/CRM, and the description names specific verbs and resources: top, get, note, tag, and suggest_follows. It is clearly distinguished from feed- or discovery-style tools such as inbox and scout by focusing on per-person engagement history and follow-back optimization.

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 concrete guidance on when to use suggest_follows and recommends pairing with scout(circle=true) to find posts to engage with. It does not explicitly state when not to use this tool versus siblings like inbox, who, or conversation, so it misses the highest level of exclusionary guidance.

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