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

With no annotations provided, the description must disclose behavioral traits on its own. It mentions the returned metrics but does not state that the operation is read-only, that results are sorted by 'top', or how the days and limit parameters affect behavior, which is a gap in transparency.

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 a single concise sentence that gets directly to the point without unnecessary filler. It is appropriately sized for the tool's simplicity.

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 absence of an output schema places more responsibility on the description to explain returns; while it gives examples ('views and visitors'), it lacks specificity about ordering, default limit, or the exact output structure. It also does not reference sibling tools, so context is only partially complete.

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 input schema already fully documents both parameters (days and limit) with descriptions and defaults, so the description adds no extra parameter-level meaning. The baseline of 3 applies because schema coverage is 100%.

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 states a specific action ('Get analytics data') applied to a defined resource ('top authors from Parse.ly'), and includes result details ('metrics like views and visitors by author'). This clearly distinguishes it from sibling tools focused on posts or tags.

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 implies use for author-level analytics but does not explicitly state when to use it versus sibling tools like get_analytics_posts or get_analytics_tags. No exclusions or alternatives are mentioned, leaving usage guidance implicit.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It mentions that the tool returns metrics and supports date ranges, but does not add deeper context such as pagination, sorting behavior, or how 'top' is determined. This is minimal but not misleading.

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 two short sentences, front-loaded with the core action and resource. Every word earns its place with no redundancy or 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?

Despite 9 parameters and no output schema, the description is very brief. It does not explain what 'top' means, how parameters interact (e.g., days vs period_start), or what the response structure looks like. The schema covers parameter details, but the overall tool context is insufficient.

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 the baseline is 3. The description adds no parameter-specific detail beyond what the schema already provides; it only mentions generic support for date ranges, which is already covered by period_start/period_end/days fields.

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 tool retrieves analytics data for top posts from Parse.ly, using a specific verb ('Get') and resource ('analytics data for top posts'). This distinguishes it from sibling tools like get_analytics_authors or get_analytics_tags.

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?

No explicit guidance on when to use this tool versus alternatives. The description implies it is for post-level analytics, but does not mention when it should be preferred over author/tag analytics or search_content. No exclusions or alternative tool mentions are provided.

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

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

No annotations are provided, so the description carries the full burden. It discloses the return value (metrics like views and visitors by tag) but does not mention sorting criteria for 'top', pagination behavior, or other operational details. Acceptable for a simple read operation but limited.

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 two concise sentences, front-loaded with a clear action verb, and contains no fluff or repetition. Every word earns its place.

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 simple 2-parameter read-only tool, the description adequately states the purpose and return type. It could clarify what 'top' means (e.g., sorted by views) but overall provides sufficient context given the schema covers parameters.

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% for both parameters (days and limit), so the baseline is 3. The description adds no additional semantics beyond the schema's field descriptions.

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 tool gets analytics data for top tags from Parse.ly, with a specific verb ('Get') and resource ('top tags'). This distinguishes it from sibling tools like get_analytics_posts and get_analytics_authors by focusing specifically on tags.

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 implies usage for tag-level analytics but does not explicitly state when to use this tool vs. the sibling analytics tools, nor does it provide exclusions or alternatives. Sibling names suggest alternatives, but no direct guidance is given.

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

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It discloses the core read operation and the ability to filter by referrer type and date range, but it does not describe the return format, pagination behavior, or any limitations. It is not contradictory but lacks depth.

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 two sentences with the primary action and resource front-loaded. Every word contributes: it names the tool, the data source, the referrer types, and a key capability. No redundant or filler wording.

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?

Given the tool has 9 parameters and no output schema, the description provides a high-level result ('Shows where traffic is coming from') and a key feature (date ranges), but it does not explain the return structure or mention filtering options like domain or section. It is adequate but not comprehensive for a tool of this complexity.

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 the baseline is 3. The description adds a hint about date ranges being useful for comparison analysis, but it does not add meaning beyond what the schema already provides for any of the 9 parameters.

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 it fetches referrer data and specifies the types ('social', 'search', 'other', 'internal'), which distinguishes it from sibling analytics tools focused on posts, authors, tags, shares, or content search. The verb 'get' and resource 'referrer data' are specific and unambiguous.

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 offers a use case ('Supports specific date ranges for comparison analysis') but does not explicitly mention alternatives or when not to use this tool. The context is implied rather than explicit, and there is no comparison with sibling tools like get_analytics_posts or get_shares.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It clearly indicates this is a read-only operation and specifies the output includes total shares and platform breakdown, but it does not mention potential behavior such as response format, pagination, sorting, or rate limits. This is adequate but not richly transparent.

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 two short sentences, front-loaded with the primary action and resource, and includes a useful output summary. Every word earns its place; there is no redundant detail.

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 simple tool with two optional, well-documented parameters and no output schema, the description sufficiently conveys what the tool does and what the response contains (total shares and platform breakdown). It lacks an explicit return type, but the overall context is complete enough for an AI agent to invoke it correctly.

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?

Input schema already covers both parameters (days and limit) with descriptions and defaults, so schema coverage is 100%. The description adds no extra parameter-level meaning, but given full schema coverage, a baseline of 3 is appropriate.

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 uses a specific verb ('Get') and identifies a distinct resource ('social share data for posts from Parse.ly'), and further clarifies it shows total shares and breakdown by platform. This clearly differentiates it from sibling tools like get_referrers or get_analytics_posts, which focus on other analytics dimensions.

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?

Usage is implied: use it when you need social share counts for posts. However, there is no explicit guidance on when to choose this tool over siblings such as get_analytics_posts or get_referrers, nor any exclusions or alternative recommendations.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the basic search function and omits details about pagination, sorting, return format, or any side effects. This is minimal value beyond the schema.

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 two short sentences with zero wasted words. It front-loads the core action and resource, making it easy to scan.

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?

Despite a comprehensive schema with 11 parameters, the description gives no context about what the response contains, how pagination works, or how to structure complex queries. With no annotations or output schema, the description is too sparse for a tool of this complexity.

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 schema covers 100% of parameters with descriptions, so the baseline is 3. The description's phrase 'by keyword' aligns with the query parameter but adds no new meaning to the other parameters, which are already well-documented in the 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?

The description clearly states the tool's action ('Search') and resource ('Parse.ly content'), specifying content types (articles, posts, pages). It distinguishes itself from sibling analytics tools by focusing on content retrieval rather than analytics metrics.

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 implies usage for finding content by keyword, which differentiates it from sibling analytics tools, but it does not explicitly state when to use this tool versus alternatives or provide exclusions (e.g., for analytics use get_analytics_posts).

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