mktg.query_analytics

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits, but it fails to do so. It does not explicitly state that the tool is read-only, mention rate limits, authentication requirements, or describe the return format. The verb 'Query' implies a read operation, but no additional context is given about what happens when filters are applied, how results are paginated, or whether any side effects occur. This is a significant gap given the lack of 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 concise and well-structured, consisting of two sentences. The first sentence front-loads the core purpose with a verb and resource, while the second sentence adds helpful examples of the data types it covers. There is no redundant or filler content; 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?

Given that this is a relatively simple query tool with three optional parameters and no output schema, the description is minimally adequate. It fails to mention what the tool returns (e.g., raw events vs. aggregated metrics) and lacks any usage context. However, the simplicity of the tool and the high schema coverage mitigate the need for extensive explanation. A more complete description would clarify the return format and any implicit behavioral constraints.

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 description coverage is 100%, with each parameter (since, user_id, event_type) having a clear description. The tool description adds a bit of context by listing example event types (page views, API calls, feature usage) that align with the event_type parameter, but it does not add significant meaning beyond the schema. The baseline score of 3 applies since the schema already provides adequate parameter documentation.

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 function with a specific verb ('Query') and the resource ('user analytics and event data'). It enumerates the types of data (page views, API calls, feature usage, user engagement metrics), making its scope understandable. However, it does not explicitly differentiate itself from sibling tools like it.query_audit_log or fin.query_invoices, which also deal with data queries, though the domain is implicitly distinct.

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 no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites, exclusions, or preferred contexts. It only describes what the tool does, leaving the agent to infer usage scenarios from the tool name and description. There is no mention of when not to use it (e.g., for audit logs or financial data).

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