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

Annotations already declare readOnlyHint=true, so the description only needs added context, and it delivers: results are permission-scoped ('you can access') and span all teams, and it discloses derived fields such as overdue counts and earliest overdue item. It stops short of covering pagination or result-size behavior for an unbounded cross-team listing.

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 action and effect, then the return contents, then the calling rule. Dense with useful content, though the long enumeration of returned fields plus the two behavioral directives makes it slightly heavier than necessary.

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?

No output schema exists, and the description compensates by describing return contents and their meaning (including to-do counts and earliest overdue item) plus access scoping. An agent has everything needed to call it and interpret the result.

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?

Zero-parameter tool, so the baseline is already high, but the description goes further by explaining that the returned property ID is required as the `property` argument on every other tool — cross-tool semantics an agent cannot infer from an empty schema.

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?

Specific verb plus precisely scoped resource: lists every AIdata property accessible through the connector across all teams, and enumerates the returned fields (ID, name, team, connections, permission level, to-do counts). This clearly separates it from siblings like list-todos or list-skills, which list different resource types.

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?

Explicitly states when to call it ('Call this first in a conversation') and why (to learn which tools will work on each property), plus an explicit hand-off rule: if a property shows an overdue to-do, call list-todos on it and inform the user. Both the usage condition and the named alternative with its trigger are present.

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