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

Annotations already declare readOnly/openWorld/non-destructive, yet the description adds real value: it explains the data comes 'through the company's connected GitHub token' (auth/source context) and constrains events to a ninety-day window. The 'Pass your agent_name' instruction is a useful behavioral cue. It does not disclose rate limits or how maxResults caps results, keeping it short of a 5.

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, front-loaded with the concrete return surface, and the short 'Pass your agent_name. Read-only.' close is efficient. The investor-thesis sentence is editorial but earns some place by clarifying intent; overall tight 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?

An output schema exists, so return-value explanation is correctly omitted, and read-only/auth/time-window context is covered. However, with five loosely documented parameters and no note on pagination or how maxResults interacts with the ninety-day window, an agent could still call it incorrectly.

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 description coverage is only 20% across five parameters, so the description must carry the burden. It only addresses agentName ('Pass your agent_name') and implicitly the username ('one GitHub user's profile'). It says nothing about companyId, maxResults, or the nested connectionId wrapper, leaving most parameters undocumented in both schema and description.

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+resource triple: the user's public profile, recently pushed repositories, and public events from the last ninety days. This is far more precise than 'get github activity' and makes the data surface unambiguous. It doesn't name a sibling, but no competing GitHub tool exists in the sibling list, so differentiation is unneeded rather than absent.

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 'dated thesis signal, never proof of an investment interest' line frames the analytical purpose but does not state when to call this versus alternatives, nor any exclusions or prerequisites. It provides interpretive context rather than actual usage guidance, leaving the agent to infer the trigger conditions.

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