Fathom Analytics MCP by usefulapi

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

Annotations already declare destructive=true, idempotent=true and openWorld=true, so the safety profile is partly covered. The description adds real value beyond that: it scopes the destruction ('The event and its completion data stay') so an agent can reassure itself the event isn't deleted, and it discloses the manage-token requirement.

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?

Three short sentences, each earning its place: effect, non-destructive scope, prerequisite. The core effect is front-loaded and there is no 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?

For a two-param mutation with no output schema and full annotation coverage, the description supplies the essential side-effect and auth context an agent needs. It doesn't describe the response shape, which is a minor omission given no output schema exists.

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 both parameters (site_id, event_name) are already fully documented in the schema, including where to list valid values. The REST path 'DELETE /sites/{site_id}/events?name=' restates which parameter maps to what but adds no new semantic detail, so the baseline of 3 applies.

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?

States a specific verb and resource ('Remove the currency set for an event') plus the resulting state ('uses the site's default again'). This cleanly distinguishes it from the inverse sibling fathom_set_event_currency without needing to open either schema.

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 clarifies the effect and the condition (reverting to site default) and states the prerequisite ('Needs a manage token for the site'). It never names the sibling set_event_currency explicitly, so the when-to-use-this-vs-that routing is implied rather than spelled out.

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?

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the bar is lower. The description adds value beyond them by disclosing the auth requirement (manage token) and the observable effect (the milestone appears on the site's reports), though it says nothing about duplicate-name behavior or error conditions.

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?

Three compact sentences: purpose first, then constraint, then endpoint. Every sentence carries distinct information with no repetition 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?

For a three-required-param create tool with no output schema, the definition covers purpose, auth prerequisite, visible effect, and endpoint. It is nearly complete, though it omits return value expectations and any uniqueness constraints on the milestone name.

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 schema already documents name, site_id, and milestone_date (including format, length limit, and the fathom_list_sites cross-reference). The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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 ('Add') plus resource ('a milestone'), with a parenthetical that defines what a milestone actually is (a dated annotation shown on reports, e.g. a launch). This distinguishes it cleanly from fathom_update_milestone, fathom_get_milestone, and fathom_delete_milestone without the agent needing to open another schema.

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 states a prerequisite ('Needs a manage token for the site'), which is useful gating information, but gives no when-to-use vs. when-to-use-an-alternative guidance (e.g. update vs. create). Usage is only implied by the verb.

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 annotations already declaring non-read-only, non-idempotent, non-destructive behavior, the description adds the real gaps: it requires an Admin token (authorization requirement), it returns the new site id used in the tracking code (a return-value behavior no output schema covers), and it names the endpoint POST /sites. It does not discuss rate limits or failure/duplicate-name behavior, keeping it short of a 5.

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?

Three tight sentences: purpose and return value first, then prerequisites and conditionals, then the HTTP endpoint. Zero padding and every clause carries information.

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 six-parameter create tool with no output schema and no nested objects, the description covers what it does, the auth prerequisite, the conditional parameter couplings, and the return value. Nothing an agent needs in order to call it correctly is missing.

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 coverage is 100%, so the baseline is 3, but the description usefully consolidates the cross-field conditional dependencies (private sharing implies share_password; multi_domain implies multi_domain_option) into a single readable clause, saving the agent from auditing individual schema entries. It adds no format detail beyond the schema, so it stops short of 5.

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?

States a specific verb and resource ('Create a new site in the Fathom account') and immediately differentiates itself from siblings like fathom_update_site and fathom_get_site by noting it returns the new id used in the tracking code. An agent can identify the tool's role without opening the schema.

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?

Gives concrete context for invoking it: an Admin token is required, and the conditional dependencies for share_password and multi_domain_option are spelled out. It doesn't give explicit when-not-to-use guidance or point at alternatives, but for a straightforward create op the context is clear.

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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is partly covered. The description adds genuinely new behavioral context: the operation is irreversible ('Cannot be undone'), the required authorization (manage token), and the precise blast radius (annotation gone, traffic data preserved). It stops short of describing error behavior on repeat calls, which matters given the idempotent hint.

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?

Three short sentences, front-loaded with the irreversible action and its scope limitation, followed by the prerequisite and the endpoint. No filler; every clause carries information.

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 two-parameter destructive tool with no output schema, the description covers purpose, irreversibility, scope of effect, and auth requirement – everything an agent needs to decide and invoke 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?

Schema description coverage is 100% – both parameters carry their own descriptions, formats, and discovery hints (fathom_list_sites, fathom_list_milestones). The description only restates them in the REST path template, adding no meaning beyond the schema, so the baseline of 3 applies.

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?

States a specific verb and resource ('Permanently delete a milestone') and immediately narrows scope by clarifying that only the annotation is removed while traffic data is untouched. This clearly distinguishes it from fathom_update_milestone, fathom_create_milestone, and fathom_get_milestone.

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 establishes prerequisites ('Needs a manage token for the site') and the consequence of use, which implies when it is appropriate, but it never names an alternative or states an explicit when-not-to-use condition (e.g. use update_milestone to disable tracking instead of deleting). Usage is inferable but not spelled out.

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?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuine context beyond them: the required token privilege (Admin, * scope) and the underlying GET /account endpoint, both of which matter for a privileged read.

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?

Three compact clauses with the resource and its fields front-loaded, then the auth requirement, then the endpoint. Telegraphic but every clause carries information; no 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?

With no output schema, the description usefully names the returned fields and the auth requirement. For a no-parameter read tool this is close to complete; only the response shape details (types, whether other fields are present) are left implicit.

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 tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly says nothing about inputs.

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?

Names a specific resource (the Fathom account) and enumerates the returned fields (id, name, email), which is more than a tautology. It doesn't explicitly contrast with siblings like fathom_get_token or fathom_get_site, so an agent must infer the distinction from 'account that owns the API token'.

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?

States a concrete prerequisite: an Admin token with the * scope. There is no guidance on when to prefer this over related read tools, nor any exclusion conditions, so usage is only implied.

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?

Annotations only declare readOnlyHint/openWorldHint, but the description discloses unusual behaviors well beyond that: numbers returned as strings, site-timezone dates, hour grouping limited to ≤7-day ranges, a 500-row default with 1000 max and no paging, and the pre-March-2021 grouping/filtering restriction. These are exactly the traps an agent needs to know.

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 entity distinction, then layers constraints and examples. It is a dense run-on paragraph with a couple of fragment-style examples ('AI referrals = [ai_source]'), but no sentence is 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?

With no output schema, the description carries return-value burden itself and does: it states string-typed numbers, row caps, no paging, and date-coverage limits. For an 11-parameter reporting tool this is complete enough to call 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?

Schema coverage is already 100%, but the description adds mapping value: it enumerates which aggregates belong to pageview vs event, and gives worked examples tying parameters together (top pages = field_grouping [pathname] + sort_by pageviews:desc). It stops short of explaining each parameter's semantics individually, so it edges above the baseline without being exhaustive.

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?

States a specific verb and resource ('aggregate pageviews or one event over a date range') and immediately distinguishes the two entity modes. The agent can tell this is the custom reporting tool versus siblings like fathom_get_current_visitors or fathom_list_events without opening the schema.

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?

Provides concrete use-case examples (top pages, traffic sources, AI referrals, daily trend) that clearly signal when to reach for this tool, and names constraints that steer usage (narrow with filters/dates, no paging). It never explicitly names an alternative sibling (e.g., current-visitors for real-time), so it stops short of full when-not guidance.

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?

Annotations already cover the safety profile (readOnlyHint, openWorldHint), and the description adds the return shape and the underlying GET /current_visitors endpoint. It omits auth/rate-limit context, but the return structure disclosure is meaningful for a tool with no 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.

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

A single dense sentence with the core purpose front-loaded and no wasted clauses; the detailed=true behavior is tacked on exactly where it is needed.

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?

With no output schema, the description does the necessary work of describing the total plus the detailed page/referrer breakdowns. Referrer fields are not enumerated and no freshness/refresh semantics are given, but an agent has enough to call 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?

Schema coverage is already 100%, but the description adds real value beyond the schema by spelling out what detailed=true returns (top 150 pages with hostname/pathname/total, plus top 150 referrers) including the 150 cap, which the schema does not state.

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?

States a specific verb and resource with scope: live visitors on a site right now. The real-time framing clearly separates it from the historical aggregation sibling without needing to name it.

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 phrase 'right now' implies the real-time use case versus fathom_get_aggregation for historical data, but the alternative is never named and no when-not-to-use condition is given. Usage is inferable but not explicit.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the REST path and the returned field set, which is modest context but no disclosure of auth requirements, error modes, or rate limits.

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?

Two terse sentences with no filler; the payload description comes first and the endpoint path second. Telegraphic style is appropriate here, though the fragments read slightly cryptic.

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?

With no output schema, the description usefully enumerates the returned fields, and the endpoint path anchors the operation. For a two-parameter read tool this is nearly complete; only error/not-found behavior is unaddressed.

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 coverage is 100% and both parameters are documented in-schema, including where to obtain each id. The description contributes nothing beyond what the schema already states, so the baseline 3 applies.

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 names a specific verb (GET) and a singular resource, and enumerates the return fields (id, name, milestone_date, created_at, updated_at). This distinguishes it from fathom_list_milestones as a single-item fetch, though it does not name that sibling explicitly.

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?

There is no when-to-use guidance, no mention of prerequisites, and no named alternative. The endpoint path implies a direct lookup by id, but nothing in the description tells the agent when this is preferable to fathom_list_milestones.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real value beyond them by listing the returned fields (id, name, sharing, timezone, created_at) and the underlying GET endpoint, which matters because there is no output schema. It still omits auth requirements and error behavior.

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?

Two short, front-loaded fragments with zero filler: the resource and its returned shape come first, then the endpoint. Nothing is padded or repeated from the title or schema.

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 single-parameter read with no output schema, the description supplies the return field set, including the sharing enum, which is the main thing an agent would otherwise lack. It stops short of documenting the response structure precisely or noting auth/failure modes.

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% and the schema already explains the site_id format, the tracking-code correspondence, and points to fathom_list_sites as a discovery path. The description adds nothing about the parameter, so the baseline of 3 applies.

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?

Names a specific retrieval ("One site") and enumerates the fields it returns, which is more than a restatement of the title. It implies single-site scope versus the sibling fathom_list_sites, but never names that sibling to draw the contrast explicitly.

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 phrase "One site" implies the usage condition (fetch exactly one known site by id), which is enough to distinguish it in practice from fathom_list_sites. However there is no explicit when-to-use/when-not guidance, no prerequisites, and no naming of alternatives such as fathom_update_site or fathom_list_sites.

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?

Annotations already declare readOnlyHint and openWorldHint, so safety is partly covered, and the description adds genuinely useful context beyond them: the secret value is never returned, and the ability-string vocabulary is decoded. It does not describe output shape or any rate limits, but for a no-arg read that is acceptable.

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?

Two compact sentences plus a bare endpoint, front-loaded with the resource and the key safety fact (no secret returned). The permission-legend parenthetical is dense but earns its place since those strings are otherwise opaque.

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?

With no output schema, the description carries the return-value burden and does so: name, permission abilities, timestamps, and the explicit exclusion of the secret. Complete enough for an agent to call it and interpret the result, though the exact timestamp fields remain unspecified.

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 tool takes zero parameters, so the baseline is 4; there is no parameter meaning for the description to clarify or obscure. The description instead spends its space on return-value semantics, which is the right allocation here.

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?

States a specific verb and resource ('the connected API token's name, permissions... and timestamps') and enumerates exactly what is returned. An agent can distinguish it from siblings like fathom_get_account or fathom_get_site without opening any schema.

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?

'Good first call to know which tools will work' gives clear situational guidance for when to invoke it. There is no explicit statement of alternatives or when-not-to-use, but the sequencing advice is actionable.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real behavioral value: sort order (by name), which events are included (all tracked names plus those with a currency), paging via next.starting_after, and the underlying endpoint.

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?

Dense and front-loaded: the resource and scope lead, then the identifier guidance, then paging, then the endpoint. Every clause earns its place with no 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?

With no output schema, the description carries the return burden and does so reasonably: it describes what the list contains and its ordering, and fully explains paging. Minor gap is the exact shape of each returned record, but the essentials for correct invocation are present.

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 coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by framing site_id/event identification and the paging cursor relationship (pass next.starting_after), clarifying the semantic role of ids within paging.

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?

States a specific verb and resource ('List a site's events') and clarifies the domain with '(conversions/goals)'. It distinguishes itself from siblings like fathom_get_aggregation by explaining that events are identified by name for use elsewhere, leaving no ambiguity about what this tool returns.

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?

Clearly routes the agent: identify events by name and use it as event_name in fathom_get_aggregation, and warns that the id is only a paging cursor. It gives positive context and an alternative relationship, though it does not state explicit when-not conditions for this list tool.

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?

Annotations already establish readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely useful behavior beyond that: default ordering ('oldest first'), the pagination cursor mechanism, and the underlying REST path GET /sites/{site_id}/milestones. It stops short of return-field or rate-limit detail, but the annotations carry the safety profile.

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?

Three compact sentences: purpose/definition first, then paging, then the endpoint. No filler, no redundancy, and the most decision-relevant information is front-loaded.

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 paged read-only list tool with no output schema, the description covers ordering, cursor-based paging, and the endpoint — enough to call it correctly. The only gap is the shape of returned milestone objects, which an agent could recover via the sibling fathom_get_milestone.

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%, with limit, site_id, ending_before and starting_after all documented in the schema itself. The description repeats the paging cursor ('next.starting_after') and the site_id path segment, adding no semantics the schema lacks. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

States a specific verb (list) and resource (a site's milestones), then defines the domain term inline as 'dated annotations on reports, such as a redesign launch or a campaign start'. That definition plus the required site_id and ordering ('oldest first') clearly distinguishes it from the singular fathom_get_milestone and the unrelated fathom_list_events/fathom_list_sites siblings.

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 the listing use case and gives concrete paging guidance ('Paged: pass next.starting_after'), which is actionable. However, it never states when to use this instead of fathom_get_milestone for a single record, nor any preconditions such as needing a valid site id from fathom_list_sites beyond what the schema already says.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered, but the description adds genuinely useful context beyond them: the Admin / all-sites read-only token requirement, the token-scoping failure mode, result ordering, and cursor paging. It stops short of 5 only because it says nothing about rate limits or error behavior on an unscoped token.

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?

Four short sentences, all front-loaded: purpose and return fields first, then auth constraint and alternative, then paging, then the HTTP path. No sentence is redundant.

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?

With no output schema, the description compensates by enumerating the returned fields, and it covers auth prerequisites, the token-scoping exception, the sibling alternative, and paging. Nothing an agent needs to invoke this correctly is missing.

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 limit, ending_before and starting_after are already documented in the schema. The description's paging note ('pass next.starting_after') largely restates the schema's own wording for starting_after and adds no new semantics, so the baseline of 3 applies.

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 and resource (list sites the token can read), lists the returned fields (id, name, sharing, timezone, created_at) and the ordering (oldest first). It is clearly distinguished from the singular fathom_get_site sibling referenced in the description.

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?

Gives explicit when-not guidance: 'a token scoped to a single site cannot list sites, so use fathom_get_site with that site id instead,' which names the alternative and the condition that selects it. Paging usage is also specified ('pass next.starting_after').

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?

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds two things annotations cannot: the manage-token authorization requirement and the fact that the currency can be set before the event is ever tracked. It does not clarify what the 'destructive' overwrite of an existing currency value actually does, which is the one remaining gap.

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?

Two front-loaded sentences that state action, timing, and auth before trailing the raw endpoint. Tight overall, though the endpoint string and the restatement of the verb from the title add little for an agent.

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 3-required-param mutation with no output schema, the description covers the action, the identifier, the auth requirement, and the notable pre-tracking timing. Annotations carry the rest of the behavioral surface; only the effect of overwriting an existing currency is unstated, which is a minor gap.

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 site_id, event_name, and currency (with its full enum) are already well documented in the schema. The description only restates 'by event name' and adds no format, casing, or selection nuance beyond what the schema provides, matching the baseline 3 for high-coverage schemas.

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?

States a specific verb (set), resource (an event's currency/value), and the selector (by event name), which clearly distinguishes it from the sibling fathom_clear_event_currency, even though that sibling is not named explicitly. It also adds the pre-tracking scope, so an agent knows what this does without opening the schema.

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?

Gives a real usage condition — 'works before the event is first tracked' — and the prerequisite 'Needs a manage token for the site', which tells the agent when it can act. It stops short of explicitly contrasting with fathom_clear_event_currency or stating when not to use this tool, so it is clear context rather than full when/when-not guidance.

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?

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=true, so the safety profile is covered. The description adds value beyond that with the manage-token authorization requirement and the concrete endpoint (POST /sites/{site_id}/milestones/{milestone_id}); it does not explain what the overwrite destroys, but the remaining gap is modest.

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?

One compact sentence front-loads the action and scope, followed by the two facts an invoker most needs (required fields, auth) and the endpoint. No 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?

For a four-parameter mutation tool with no output schema, the description covers action, scope, required inputs, auth, and transport. Idempotency and destructive semantics are delegated to annotations, which is acceptable, though failure modes (invalid milestone id, insufficient token) are left to the API.

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 coverage is 100%, so all four parameters are already documented in the schema, including the id sources (fathom_list_sites, fathom_list_milestones). The description only restates that name and milestone_date are required, a fact the schema's required array already carries, so baseline 3 applies.

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?

States a precise verb+resource ('Rename or re-date a milestone') and sharply bounds the scope to two mutable fields, which distinguishes it from fathom_create_milestone, fathom_delete_milestone, and fathom_get_milestone without needing to name them.

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?

Gives real invocation context: both name and milestone_date are mandatory, and a manage token is required for the site. It stops short of naming alternatives (e.g. fathom_get_milestone to first read the existing date), so it is clear context without explicit when-not guidance.

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?

Annotations already declare readOnly=false, destructive=true, idempotent=true, openWorld=true, so the safety bar is lowered; the description still adds real context: the report-bucketing side effect of a timezone change, the manage-token auth requirement, partial-update semantics, and the underlying POST /sites/{site_id} call. It does not explain what aspect of this update is "destructive."

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?

Three dense sentences with no filler, front-loading what can be changed before the invocation hint, side effect, auth requirement and endpoint. The endpoint string is marginal but harmless.

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 7-parameter partial-update tool with only one required field and no output schema, the description covers the mutation surface, the partial-send convention, the auth prerequisite and a key side effect. Conditional dependencies (share_password with sharing=private, multi_domain_option with multi_domain) are left entirely to the schema, which is acceptable at 100% coverage.

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 coverage is 100%, so every parameter including share_password and multi_domain_option is already documented with format, enum and conditional requirements. The description's field list duplicates the schema rather than adding syntax or interaction detail, which is the baseline 3 case.

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?

States a specific verb+resource ("Change a site's") and enumerates the mutable attributes (name, sharing, timezone, multi-domain), which is well beyond a restatement of the title. It does not explicitly contrast with siblings like fathom_create_site or fathom_get_site, but the mutating scope is unmistakable.

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?

"Send only what changes" gives clear PATCH-style invocation guidance and "Needs a manage token for the site" states a prerequisite, which is more than nothing. However, no alternative tools are named and there is no explicit when-not (e.g., use fathom_get_site to inspect current values first).

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