mazarbul

Overview Schema Source Related Servers Discussions Admin

count

Compute the exact total of entities matching an AIP-160 filter, optionally returning per-value group breakdowns via groupBy.

Instructions

Count entities matching an AIP-160 filter — the deterministic answer to "how many …". With groupBy, returns a per-value breakdown (e.g. people per status) instead of a single total. Same filter grammar as the entities tool. Scope: defaults to project+personal; pass scopes:["team"] to include team entities.

Input Schema

Name	Required	Description
`kind`	No	Convenience prefilter to one entity kind, AND-combined with filter.
`limit`	No	Max groups to return when groupBy is set, most-populous first. Defaults to 50. Ignored without groupBy.
`filter`	No	AIP-160 filter expression selecting which entities to count. Same grammar as the entities tool: reference entity columns (kind, displayName, confidence, resolutionStatus, createTime), fact slots by state_key (e.g. status = "pending"), and related("predicate", "target"). Operators = != < > <= >= : with AND / OR / NOT.
`scopes`	No	Scope filter: which data partitions to count. Allowed values: project, personal, team. Defaults to [project, personal] when omitted — team entities are hidden unless you pass scopes:["team"].
`groupBy`	No	When set, return a per-value breakdown counted by this field instead of a single total. The field is an entity column (kind, resolutionStatus, …) or a fact slot state_key (status, …); entities with no open fact for that slot bucket under the empty value.

Output Schema

Name	Required	Description	Default
`count`	No	Total matching entities. Present when groupBy is not set.
`groups`	No	Per-value breakdown, most-populous first. Present when groupBy is set.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 31, 2026

TDQS

A4.5/5.0

Behavior4/5

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

No annotations, so the description carries the behavioral burden and does well: it discloses that team entities are hidden unless scopes:["team"] is passed, that groupBy switches to a per-value breakdown, and that entities without an open fact bucket under the empty value. Minor gaps on return shape are offset by the output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, then scope and groupBy behavior in tight sentences. No filler; each sentence carries distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 0 required params, full schema coverage, and an output schema present, the description covers the behavioral essentials an agent needs: scope defaults, groupBy semantics, and filter grammar reference. Nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% so the baseline is 3, but the description adds meaning beyond the schema — the team-hidden scope default and the groupBy bucketing behavior — which helps an agent reason about parameter outcomes rather than just syntax.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Count entities') and frames it as 'the deterministic answer to how many', which distinguishes it from a list/query tool. The groupBy breakdown and scope language further narrow what the tool returns.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains the scope default (project+personal) and the condition to include team entities, and points to 'the entities tool' for the filter grammar. It doesn't explicitly say when to prefer this over the 'entities' or 'query' siblings, but the usage context is clear.

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