Census MCP by usefulapi

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

Annotations already declare readOnlyHint=true, so the safety profile is covered and the burden on the description is lower. The description adds the underlying endpoint (GET /destinations/{id}) but says nothing about 404/error behavior or authentication, so it is only minimally additive.

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 sentences, front-loaded with the operation and scope. The second sentence is largely endpoint mapping rather than agent-facing semantics, which is minor filler but still compact overall.

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 one-parameter read tool with no output schema and annotations covering safety, the description supplies everything needed to invoke it correctly. Only edge-case behavior (not-found, auth) is left 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% and the single 'id' parameter is fully documented as a numeric id passed as a string. The description restates 'by id' without adding format, validation, or lookup semantics, 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?

States a specific verb ('Get') and resource ('a single destination connection') qualified by 'by id', which distinguishes it from census_list_destinations through the word 'single'. It does not explicitly name the sibling alternative, so it falls just short of a 5.

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 by 'single ... by id' — fetch one destination when you already have its id — but there is no explicit when-to-use vs when-to-use-list guidance and no stated prerequisites. The REST endpoint mapping adds orientation but not selection 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?

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the bar is lower. The description adds one useful detail — that the response includes the model's SQL/query — but says nothing about error behavior for a missing/non-numeric id.

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 with the essential verb/resource/payload front-loaded, followed by the REST mapping. Nothing is padded, though the 'Census: GET /models/{id}' clause adds little beyond the name.

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 tool with annotations covering safety and no output schema, the description plus schema is nearly sufficient; the note about returned SQL/query is the key extra context an agent needs, with only minor gaps around 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 coverage is 100% and the schema description explains the id as a numeric id passed as a string. The description only echoes 'by id' and adds no format or constraint information beyond the schema, 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 specific verb and resource ('Get a single model by id') and clarifies the payload includes the SQL/query, which distinguishes it from a bare metadata fetch. It implicitly separates from census_list_models by specifying a single record, though no sibling is named.

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 'by id' phrasing implies the call is for retrieving one known model, which contrasts with list_models, but the description never states when to prefer this over census_list_models or census_get_sync, nor any prerequisite such as a valid id.

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?

The readOnlyHint annotation already establishes that this is a safe, non-mutating read, so the description carries a lighter burden. It adds the underlying endpoint (Census: GET /sources/{id}), which confirms the operation maps to a single-resource fetch, but it says nothing about not-found behavior, permissions, or rate limits. Adequate but thin for a read tool.

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 sentences, zero filler, with the operation front-loaded before the endpoint reference. Nothing is padded or 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?

For a simple single-resource read with no output schema, a 100%-covered schema, and a readOnlyHint annotation, the description supplies everything needed to invoke the call correctly. Only minor gaps remain, such as error/not-found behavior, which an agent might reasonably want.

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 a single required 'id' string parameter fully documented as a numeric id passed as a string. The description restates 'by id' without adding format, scoping, or validation guidance 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?

The description states a specific verb (Get) and resource (a single source connection) and scopes it to retrieval by id, so an agent can distinguish it from census_list_sources or census_get_destination. It is clear and precise, though it never explicitly names a sibling as the alternative, which keeps it out of the top band.

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 'by id' weakly implies the tool is for when a source id is already known, but there is no explicit when-to-use statement, no contrast with census_list_sources for discovery, and no note on what to do if the id is unknown. Usage must be inferred.

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?

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the description need not restate safety. It adds that the response is the 'full configuration', a small hint about return completeness, but nothing about not-found handling, permissions, or pagination.

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 sentences with the core action front-loaded and zero filler; the endpoint reference is compact and useful.

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 single-resource read with readOnlyHint and a single fully documented parameter, the description covers what the tool does and what it returns at a high level. With no output schema, a bit more detail on the returned object would help, but nothing essential 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% and the single id parameter is fully documented in the schema, so the baseline is 3. The description only restates 'by id' and adds no format or constraint detail beyond 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?

States a specific verb (get) and resource (a single sync's full configuration), and the REST endpoint mapping confirms the scope. It implicitly distinguishes itself from census_list_syncs by saying 'a single sync', but does not name any 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?

The 'by id' phrasing implies usage (retrieve one sync when you have its id), but there is no explicit when-to-use guidance, no mention of the list alternative, and no stated behavior for a missing/invalid id.

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, so the safety profile is covered. The description adds genuine context by enumerating the payload contents (status, counts, errors), which compensates somewhat for the absent output schema, though it says nothing about errors for missing/invalid ids.

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 sentences, zero filler, and the operation is front-loaded before the REST mapping. Every clause 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?

With no output schema, the enumeration of returned fields (status, counts, errors) is the right compensating detail, and readOnly is handled by annotations. It is nearly complete; only the id source and error behavior are 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 the schema itself notes the id is numeric but passed as a string. The description adds no detail beyond 'by id', so the baseline 3 for schema-driven parameters 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 (Get) and resource (a single sync run) and explicitly scopes it to one item by id, which cleanly separates it from the sibling census_list_sync_runs. The REST mapping (GET /sync_runs/{id}) reinforces the intent.

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 'by id' and 'a single sync run' imply the lookup use case and contrast with the list sibling, but the description never explicitly says when to use this versus census_list_sync_runs or where an id comes from. 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 already declare readOnlyHint=true, so the safety profile is covered. The description adds the useful domain semantics of what a destination is, but discloses nothing about pagination behavior, total counts, or result shape beyond the raw endpoint reference.

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 tight sentences with the core definition front-loaded and the API reference trailing. The 'Census: GET /destinations' fragment is mildly redundant but adds provenance, not enough to drop below 4.

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 read-only, fully-schematized list endpoint with no output schema, the description covers the essential purpose and domain framing. Missing return/pagination context is a minor gap given the annotations already signal a safe read.

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 both page/per_page parameters are documented in the schema, so the description correctly defers to it. The description adds no syntax, defaults, or filtering semantics beyond what the schema already provides, 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 specific verb (List) and resource (configured destination connections), then defines the resource in domain terms ('SaaS apps data is synced INTO') with concrete examples. This lets an agent distinguish it from the sibling census_list_sources without opening 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?

Usage is implied by the definition of 'destination' versus 'source', which is the key distinction among the list_* siblings. However, it never explicitly says when to use this versus census_list_sources or census_get_destination, so the agent must infer the routing.

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, so the safety profile is covered. The description adds genuine domain context by defining what the returned entities are (queries that produce rows to sync) and mapping to the underlying endpoint, but says nothing about pagination behavior despite page/per_page parameters.

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 tight sentences with zero waste; the verb and resource lead, the domain clarification follows, and the endpoint reference is a compact trailing note.

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, read-only list tool with full schema coverage and no output schema, the description covers purpose, scope, domain object, and endpoint. The only minor gap is pagination semantics, which is largely covered by the schema itself.

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 both page and per_page fully documented in the schema, so the baseline of 3 applies. The description adds no parameter-level detail beyond what the schema already provides.

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 SQL models / datasets defined in the workspace') and even clarifies what a model is ('the queries that produce rows to sync'), so an agent immediately knows the domain object. It does not explicitly name the singular sibling census_get_model to contrast scope, which keeps it just short of a 5.

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 rather than stated: the workspace-level listing scope suggests this is the inventory/browse operation, with census_get_model presumably the single-item alternative. No explicit when-to-use, when-not, or alternative is named.

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, so the safe-read profile is covered structurally. The description adds only the workspace scoping and the underlying endpoint mapping (GET /segments), which is mildly useful for traceability but discloses nothing about result volume, pagination behavior, or workspace/credential requirements.

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 sentences with zero filler, and the purpose statement is front-loaded ahead of the API reference. Nothing could be removed without losing 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?

With no output schema, the description is the only place return-shape information could live, and it says only 'audience segments' without indicating what a segment record contains or that results are paged. For a simple read-only list tool this is minimally adequate but leaves a real 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 the paging semantics of 'page' and 'per_page' are already documented in the schema. The description adds no additional parameter meaning, 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?

States a specific verb and resource ('List audience segments defined in the workspace'), and the workspace scope plus the endpoints help disambiguate from the sibling get_* tools. It stops short of explicitly contrasting itself with the other list_* siblings (destinations, sources, syncs), but the resource noun is distinctive enough to select correctly.

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 statement of when to use this tool versus the other list tools, no preconditions, and no note that it returns all segments unfiltered. Usage is only implied by the verb 'list'; nothing tells the agent when this is the right call.

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?

The readOnlyHint annotation already establishes this as a safe read, so the description does not need to restate safety. It adds the underlying endpoint (GET /sources) and concrete source types, but says nothing about pagination defaults, result ordering, or what a caller gets back; for a simple list tool with annotations, this is adequate but thin.

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 sentences, purpose front-loaded, no filler. The trailing endpoint reference ('Census: GET /sources.') is marginally useful for tracing the API but does not serve tool selection.

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 zero-required-parameter read-only list operation with a fully documented schema and annotation coverage, this is close to sufficient. The only missing element is any hint about pagination behavior or result volume, which the absence of an output schema makes slightly more relevant.

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 page and per_page are documented in the schema with their purpose — so the description carries no obligation here. It adds no syntax or default-value detail beyond the schema, which is the baseline 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 (List) and resource (configured data warehouse sources) and enumerates concrete source types (Snowflake, BigQuery, Redshift, Databricks), which makes it distinguishable from census_get_source and census_list_destinations. It does not explicitly name a sibling, but the singular/plural contrast with get_source is clear.

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 contains no when-to-use statement, no prerequisites, and no named alternative. An agent must infer that this is for enumerating all sources rather than fetching one (census_get_source) or listing destinations; nothing in the text routes it.

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, so safety is covered. The description adds real value beyond that by disclosing the shape of each returned record (status, records processed, timing), which matters since no output schema exists. It omits any mention of pagination behavior despite page/per_page inputs.

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, front-loaded sentences with no filler; the resource and its returned fields come first, followed by the filter and the upstream endpoint mapping. Slightly terse on pagination, but nothing is wasted.

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 read-only list tool with a fully described schema and no output schema, the description covers the resource, returned fields, and filtering. Pagination semantics are the only notable omission, and those are partly carried by the schema.

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 page, per_page, and sync_id are already documented in the schema. The description restates the sync_id filter in plain language but adds no format, range, or default detail beyond what the schema provides — the baseline for full coverage.

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 ('List sync run history') and parenthetically enumerates what each run contains (status, records processed, timing). This distinguishes it from census_list_syncs and census_get_sync_run, though it never names those siblings 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?

Usage is only implied by the tool name and the parenthetical return summary; there is no statement of when to use this list endpoint versus census_get_sync_run for a single run or census_list_syncs for sync configurations. The 'Filter by sync_id' note is a parameter hint rather than routing 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?

The readOnlyHint annotation already covers the safety profile, so the bar is lower, and the description adds real value beyond it: it enumerates the returned fields (id, label, status, source_attributes, destination_attributes), which matters because no output schema exists, and it maps the tool to the underlying 'GET /syncs' call. It omits pagination behavior and any auth/rate-limit context, so not 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 short sentences with zero filler: purpose and resource definition first, then return shape, then the underlying endpoint. Every clause carries information and the most decision-relevant content 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 read-only, two-parameter list tool with annotations covering safety, the description supplies the resource definition, the return fields (compensating for the missing output schema), and the API mapping. Only pagination semantics and guidance for choosing this over census_get_sync/census_list_sync_runs are absent, which are minor given the schema.

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 page and per_page are documented in the schema as pagination controls. The description adds nothing about pagination defaults, limits, or ordering, so the schema does all the work and 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 ('List syncs') and goes further by defining what a sync is ('maps a source model to a destination object and keeps them in sync'), which meaningfully separates it from the singular census_get_sync and from census_list_sync_runs. It stops short of explicitly naming siblings, so it is clear but not fully differentiated.

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 only implied: the plural 'List' plus the enumerated return fields signal this is the enumeration/overview tool, and it contrasts implicitly with census_get_sync for a single record. There is no explicit when-to-use, when-not-to-use, or named alternative, so an agent must infer the routing itself.

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, so the safety profile is covered. The description adds genuine behavioral context beyond that: an organization-level token is usually required, a non-trivial auth quirk an agent would otherwise not anticipate.

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 front-loaded sentence stating the action and scope, followed by a brief auth caveat and the API endpoint reference. Slightly cluttered by the parenthetical and endpoint tag, but nothing wasted.

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 parameterless read-only lister with annotations covering safety, this is close to complete: it says what it returns (a list of workspaces), the scope, and the auth caveat. Only the return shape/pagination is unstated, which is minor with no output schema.

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 schema carries no burden to compensate for. The description adds no parameter information, which is correct here since none exist.

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 ('workspaces') scoped to 'in the organization'. No sibling lists workspaces, and each sibling is tied to a distinct resource, so an agent can tell them apart immediately.

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 a prerequisite note about the organization-level token, which is helpful, but no explicit when-to-use or when-not-to-use guidance and no named alternatives among the sibling list tools. 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 flag destructiveHint=true; the description adds the substantive reason — this writes records into a connected external SaaS destination, i.e. changes leave the platform. It explains the full-sync escalation too, but omits auth/permission needs, whether duplicate rows can be pushed, and any rate limits or partial-failure 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 tight sentences front-loaded with the action and its blast radius, followed by the one parameter flag that changes behavior. No filler and no repetition of the title.

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 2-param mutation with no output schema and only a destructiveHint annotation, the description covers the essentials: what is triggered, what it writes to, and how to widen the scope. Missing only the post-trigger behavior (returned run id, how to track completion), which mildly limits an agent orchestrating a multi-step sync flow.

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 both parameters are already documented in the schema. The description's force_full_sync phrasing ('re-sync all rows instead of just changes') is essentially a restatement of the schema description, adding no new syntax, constraints, or defaults; 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 specific verb and resource ('TRIGGERS a sync run for the given sync id') and immediately qualifies the effect as a live write into the destination SaaS tool. That distinguishes it from every read-only sibling (census_get_sync, census_list_sync_runs, census_get_sync_run) without opening a 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 clear invocation context — use this to kick off a live sync, with force_full_sync=true as the alternate mode for re-syncing all rows. It never names a sibling or an exclusion (e.g. 'use census_get_sync_run to poll status afterwards'), so routing to it vs. the read tools is left partly to inference.

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