get_profile_analytics

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It identifies the tool as a read operation (retrieving analytics) and specifies the date format constraint. However, it does not mention pagination behavior (despite a page parameter), authentication requirements, rate limits, or what occurs if data is unavailable. The description is adequate but leaves several behavioral aspects unexplained.

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 consists of two sentences: the first clearly states the purpose, and the second adds a critical parameter constraint. It is front-loaded and concise, with no redundant information. Every word contributes to clarity and utility.

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?

The description covers the core functionality and key parameter constraint, but it lacks details about the return structure (e.g., whether results are aggregated per profile, per day, or how pagination works). Given that there is no output schema, the description should provide more guidance on what the agent can expect in the response. Overall, it is adequate for a simple query tool but incomplete in explaining output format.

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 100%, so each parameter already has a description. The description adds value by clarifying the date format requirement ('YYYY-MM-DD...YYYY-MM-DD') and the 1-year maximum span, which are not explicitly in the schema. It also references get_profiles for discovering profile IDs. This supplementary information justifies a score above the baseline of 3.

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 states the verb ('Get'), resource ('profile-level analytics'), and scope ('owned profiles', 'one or more', 'over a reporting period'). It mentions specific metrics like impressions and engagements, distinguishing it from sibling tools like get_post_analytics (which focuses on individual posts) and get_listening_topic_metrics (which covers listening topics).

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 provides a specific usage requirement: the reporting period must be in 'YYYY-MM-DD...YYYY-MM-DD' format with a maximum 1-year span. It also cross-references get_profiles for discovering profile IDs. However, it lacks explicit when-not-to-use guidance or comparison to alternatives, though the context of siblings implies the tool is for profile-level analytics rather than post or listening metrics.

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