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

With no annotations, the description carries the burden well: it discloses that collect_now requires an ACTIVE function with a PULL acquisition and an ACTIVE source, that provider failures surface as HTTP 500, and that retry retains the original attempt unchanged while returning a new evaluation. It omits auth/permission requirements and rate or pagination 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?

Front-loaded resource statement followed by a tight action/required-parameter bullet list that maps directly to the action enum. The trailing attempt JSON block is verbose but earns its place as a substitute for a missing output 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 dispatcher with no annotations and no output schema, the description supplies the per-action semantics, an error-mode note, and the returned attempt JSON shape, which covers most of what an agent needs. The undocumented pagination parameters (limit, cursor, all_pages) remain a 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 0% across 6 parameters, so the description must compensate. It documents attempt_id and fitness_function_id with their per-action meanings, but limit, cursor, and all_pages are left completely undefined in both schema and description, leaving half the surface undocumented.

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 the resource (pull collection attempts) and enumerates four concrete actions with their required identifiers, so the agent knows exactly what each operation does. It does not explicitly name or distinguish itself from siblings like polaris_fitness_functions or polaris_measurement_sources, which keeps it 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?

Per-action context is strong: collect_now is described as running outside the schedule when an immediate evaluation is needed, and retry is framed as recovery after a provider outage. No explicit when-not conditions or named alternative tools are given, but the action-selection guidance 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?

With no annotations, the description carries the full burden and does well: it discloses the 202/PENDING async contract, that the request is fulfilled by a producer pushing a submission or by pull collection, that get polls state, and that double-cancel returns 409. Missing auth/permission requirements and whether cancel is reversible keeps it from 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?

Front-loaded one-line purpose followed by a scannable per-action bullet list, then the response shape. Every line adds information; the JSON field enumeration is borderline verbose but substitutes for the absent output 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 3-action mutation tool with no annotations and no output schema, the description supplies the lifecycle states, fulfillment mechanism, error case, and the returned entity's fields. Only permission/authentication context and explicit sibling boundaries are absent.

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 0%, so the description must compensate, and it does: it maps fitness_function_id to create and request_id to get/cancel, and explains that the created id is the evaluationRequestId a producer references. It still does not state the format/type of the ids beyond what the schema shows.

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 resource ('evaluation requests') and enumerates exact verbs (create/get/cancel), so the agent knows precisely what the tool manipulates. It does not explicitly contrast itself with adjacent siblings such as polaris_measurement_submissions or polaris_evaluations, leaving the boundary to inference.

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?

Each action is given a use condition – cancel is for a PENDING request 'e.g. the triggering pipeline was aborted', create is for awaiting a producer submission, get is for polling. There is no explicit 'use X instead' routing to alternative tools, but the when-to-use guidance per action 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?

With no annotations the description carries the full burden, and it delivers meaningful traits: evaluations are immutable after recording, disposition honors approved unexpired waivers, validUntil signals staleness, and 'no data never counts as success'. Auth/rate-limit behavior is not mentioned, keeping it out of 5 territory.

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?

Tightly front-loaded: the purpose sentence comes first, then a compact action list, then the return shape. Every block earns its place, and the evaluation JSON preview substitutes for a missing output schema rather than padding.

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 6-parameter, no-output-schema reader, the description supplies the enumeration of actions, the parameters each requires, and a full field-level preview of the returned evaluation object (outcome/disposition/criterionResults/data). Sibling differentiation and error/empty-result behavior are the remaining gaps.

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 0%, so the description must carry all six parameters, and it does: action, evaluation_id, fitness_function_id, and the optional limit/cursor/all_pages are all named with their contexts. It adds meaning over the bare schema, though cursor semantics (opacity, encoding) are not spelled out.

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 ('Read evaluations') and enumerates the two read actions (get, list_by_function) with their required parameters. It does not distinguish itself from nearby siblings such as polaris_evaluation_requests, so an agent cannot tell from the text alone why it should pick this tool over that one.

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 action-selection guidance by pairing each action with its required parameter (get→evaluation_id, list_by_function→fitness_function_id) and noting pagination options for the list case. It stops short of any when-not-to-use or alternative-tool routing, which is the missing piece for a 5.

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

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

With no annotations, the description carries the full burden and does disclose key delivery semantics: acknowledged events are never redelivered, acknowledgement is idempotent per (consumer, event) pair, and cursor-less polls begin from the oldest event. It omits rate limits, auth requirements, and concurrency/multi-consumer 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?

Purpose is front-loaded, actions are bulleted, and the event JSON shape is presented compactly; no sentence is redundant. It is slightly dense but every element (action bullets, event schema) earns its place.

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

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

For a 6-param, annotation-less tool with no output schema, it helpfully documents the returned event shape and cursor behavior. The main shortfall is the undocumented all_pages flag and the unstated limit default, so it is nearly but not fully complete.

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

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

At 0% schema coverage the description must document all 6 parameters, but it only explains consumer_id (stable identity, 1-100 chars), event_ids (1-500 ids), cursor, and limit (merely 'optional'). The all_pages parameter is never mentioned and limit's default/range is unspecified, leaving real gaps.

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+resource ('consume delivery events published through the transactional outbox') and enumerates the two concrete actions (poll, acknowledge). No sibling in the list is an event-consumption tool, so the purpose is unambiguous and clearly separable from the polaris_* management/query tools.

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?

It gives explicit workflow guidance: poll returns events newer than cursor, persist nextCursor between polls, start from oldest without a cursor, and acknowledge after successful processing. It never states when not to use the tool or names an alternative action, but the operational sequence is clearly laid 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?

With no annotations, the description carries the whole burden and largely succeeds: it discloses that versions are immutable after activation, that If-Match can be passed explicitly via `revision` or defaulted to the current one, that retire is terminal while history stays queryable, and that validation has no side effects. It omits permission/auth requirements, error behavior, and pagination semantics for limit/cursor/all_pages.

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 one-line purpose followed by a scannable action/required-parameter list and then a nested spec for the one complex object argument. Despite its length, nearly every line conveys routing or schema information the agent cannot get elsewhere, so it is dense rather than padded.

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 ten-parameter, eight-action tool with no annotations and no output schema, the description covers the action surface, concurrency model, lifecycle transitions, and the full definition contract. It stops short of describing return shapes or pagination limits, which leaves some inference required for list/get responses.

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 0%, yet the description documents almost every parameter in context: squad_id, fitness_function_id, version, revision (If-Match), reason, and the limit/cursor/all_pages pagination set per action. The `definition` param — otherwise an opaque object — is spelled out in detail including required fields, camelCase key convention, criterion key pattern, enum values for comparisons and reduction/seriesPolicy, and the warning-vs-failure threshold constraint.

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 opening sentence names a specific resource ('fitness functions: versioned definitions of intent, scope, criteria, acquisition, freshness, and enforcement') and the rest of the description enumerates all eight actions with their required parameters. An agent can distinguish this definition-management tool from siblings like polaris_evaluations or polaris_fitness_targets 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?

The description gives clear per-action context: validate_version 're-runs validation without side effects', activate_version makes evaluations use the definition, retire is terminal, and update_draft_version only touches still-DRAFT versions. It does not, however, point the agent to sibling tools for adjacent tasks (e.g., polaris_fitness_function_templates for template-based creation), so the routing guidance is strong but not complete.

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

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

No annotations are supplied, so the description carries the full burden and does disclose meaningful behavior: duplicate names yield 409, adopt produces a DRAFT the squad may adapt, and the tribe retains no ownership. It omits auth/permission requirements and pagination cursor semantics beyond listing the params.

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 purpose, then structured as action-to-parameter bullets plus a template JSON shape. Efficient, though the final template JSON line is somewhat terse and assumes reader familiarity.

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?

Covers the three actions, required params, key constraints (409 duplicates, DRAFT status), and the returned template shape via the template JSON. With no output schema and zero schema coverage, this is nearly sufficient; minor gaps remain around error cases and permissions.

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 0%, so the description must compensate and largely does: it names required parameters per action (tribe_id, name, template_id, squad_id), clarifies optional params (limit/cursor/all_pages, target_ids, reason), and explains definition as a FitnessDefinition with camelCase keys matching polaris_fitness_functions. It still doesn't describe every one of the 12 parameters' types or constraints.

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 concrete verb (Manage) and resource (tribe-published fitness-function templates), then enumerates three distinct actions (list/publish/adopt). Distinguishes itself from sibling polaris_fitness_functions by scoping to tribe-published templates versus plain fitness functions.

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?

Maps each action to its required parameters and notes that adopt creates a squad-owned DRAFT while the tribe retains no ownership, which guides action selection. It doesn't explicitly state when to prefer this over polaris_fitness_functions, leaving a small gap.

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

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

With no annotations present the description carries the full behavioral burden, and it does disclose meaningful traits: create yields an ACTIVE record, transition is an explicit auditable change whose history stays queryable, and the permitted status lifecycle is enumerated. It omits permission/auth requirements, conflict or error behavior, and any rate/limit semantics, which keeps it below 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?

Front-loaded with the one-line definition, then organized as a tight per-action bullet list, with the target JSON shape last. Every line adds information, though the response-shape block makes it longer than strictly minimal.

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 13-parameter, annotation-free tool with no output schema, the description provides the action/parameter matrix and the returned target JSON shape, which is what an agent needs to call and interpret it. Gaps remain around auth requirements, error cases, and how list pagination behaves with all_pages versus cursor.

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 0%, yet the description accounts for all 13 parameters by binding each to its action, adding enum examples the schema lacks (target_kind SERVICE/DATABASE/QUEUE, criticality CRITICAL/HIGH), and noting external_reference is an object and limit/cursor/all_pages apply to list. It compensates fully for the empty schema descriptions.

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

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

States a specific verb+resource ('Manage fitness targets') and immediately defines the domain object as 'systems (services, databases, queues, ...) a squad is accountable for', which is far more than a tautology. It does not, however, contrast itself with siblings such as polaris_fitness_functions or polaris_waivers, so an agent must still infer the boundary.

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?

Each action (list/get/create/transition/history) is paired with its required parameters, which effectively maps intent to invocation, and transition is annotated as the 'explicit, auditable lifecycle change' path. There is still no explicit when-not or named alternative action for lifecycle edits, so the guidance is clear but not exhaustive.

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

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

With no annotations, the description carries the full burden and does so well: 'live' has no dependencies; 'ready' verifies PostgreSQL and returns a 503 problem document while down; success returns {"status": "ok"}. These are exactly the behavioral traits an agent needs for a health probe.

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

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

The description is front-loaded, uses a compact bullet list for the two actions, and includes the return value without any wasted sentences.

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 one-parameter health tool with no output schema, the description covers action semantics, dependency behavior, failure behavior, and success response. Nothing necessary for correct invocation 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?

The schema has only an action enum with 0% description coverage, but the description fully explains both enum values: 'live' means process liveness with no dependencies, and 'ready' means readiness to serve traffic with PostgreSQL verification.

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 and resource: 'Probe Polaris health.' It clearly distinguishes this tool from the sibling polaris_* domain tools, none of which expose health checking.

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?

It gives explicit when-to-use guidance for each action: 'live' for process liveness and restart probes, 'ready' for readiness to serve traffic. The selection criteria between the two actions are fully specified.

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

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

With no annotations, the description carries the full burden: 'Read' establishes read-only behavior and the sketch '{scope, scopeId, generatedAt, status}' discloses the return shape. But it omits auth/permission requirements, pagination behavior for limit/cursor/all_pages, and what 'retained' evaluations implies for freshness.

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 purpose sentence followed by a compact per-action list, with no filler. The final sentence on return shape is somewhat dense but earns its place given the absence of an output 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 7-parameter tool with no annotations and no output schema, the description covers the action-to-parameter mapping and gives a partial return sketch, which is meaningful. It still leaves pagination semantics, error/status meanings, and the relationship to sibling data tools undefined.

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 0%, so the description must compensate, and it does: it documents which id parameter each action requires and notes that limit/cursor/all_pages are optional and scoped to target_history. It stops short of explaining cursor format or pagination limits.

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 ('Read insight aggregates computed from retained evaluations') and enumerates three concrete action modes with distinct scopes. It implicitly separates itself from polaris_evaluations (the raw source), though it never names a sibling explicitly, so it stops short of 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?

Maps each action to its required parameter, which functions as implicit when-to-use guidance, and the '(no league table)' note hints at a boundary for tribe_overview. However, it never states when to choose this tool over polaris_evaluations or polaris_fitness_targets, nor any preconditions.

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

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

No annotations exist, so the description carries the full burden, and it does substantial work: it names the create action, its required inputs, the resulting entity shape, and the key invariant that exactly one producerId per PUSH definition governs who may submit. Gaps remain — nothing about auth/permissions to create, name uniqueness, idempotency, or 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?

Three tight paragraphs, each with a distinct job: what a producer is, what create requires, and what the returned id is for. The purpose and the required inputs are front-loaded before the structural JSON example, 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?

With no annotations and no output schema, the description supplies the entity shape and even the return contract ('the returned id is the producerId'), so an agent can both call and consume this tool. Missing authorization requirements and any statement about duplicate names or error conditions keep it from being fully complete.

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

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

With 0% schema description coverage, the description compensates by mapping inputs to the create action ('requires squad_id + name (optional description)') and by explaining that squad_id becomes parentId in the producer JSON. It does not cover input formats such as expected id shape or length limits, so it stops short of fully documented parameters.

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

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

States a specific verb and resource — 'Register measurement producers' — and operationalizes the concept ('identities authorized to PUSH measurements for a squad'), which implicitly separates it from pull-based measurement sources. It never names the dangerously similar sibling 'polaris_measurement_providers', so an agent must infer the producer-vs-provider distinction on its own.

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 conveys the workflow precondition well: you need a producer before a PUSH fitness-function definition can declare a producerId, and the returned id is the value to reference there. However, it never frames this as a choice against alternatives or states when-not to use it, and the sole action is fixed to 'create' with no guidance on updating or finding existing producers.

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

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

With no annotations provided, the description carries the full burden and does reasonably well: it discloses the return contents (query capabilities INSTANT_QUERY/RANGE_QUERY and outbound auth modes), and importantly scopes what exists today ('only NONE in v1; only PROMETHEUS is supported'). It does not describe pagination, errors, or auth requirements for calling the tool itself.

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 one-line purpose, then the action and its return contract. The 'Action:' labeling is slightly mechanical and the last clause about resource shapes is a bit tangential, but nothing is seriously wasteful.

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-action, no-argument-style catalog tool with no output schema and no annotations, the description covers purpose, return contents, and v1 limitations. It is nearly self-sufficient; only error/pagination 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?

There is a single parameter whose schema description coverage is 0%, but the parameter is a const ('list_types') and the description explains precisely what that action does and what it returns, which is the only semantic gap the schema leaves open.

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 gives a specific verb and resource ('Discover supported pull measurement providers') and names the concrete action ('list_types — returns the provider capability catalog'), so an agent knows exactly what it gets back. It does not, however, distinguish itself from close siblings like polaris_measurement_sources or polaris_measurement_producers, which occupy similar conceptual space.

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?

It explicitly tells the agent when to reach for this tool over an alternative behavior: 'Use this instead of hard-coding provider assumptions.' That is genuine usage guidance, though it does not name a sibling tool or state a when-not-to-use condition.

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

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

With no annotations, the description carries the full burden and does well: it discloses the DRAFT→ACTIVE→RETIRED state machine, the 409 rejection when a fitness-function version still depends on the source, the 422 behavior on failed probes with provider error in the detail, and that credentials are never stored or returned. It omits permission/auth requirements and whether create is idempotent, so not a perfect 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?

Front-loads purpose then lifecycle, then breaks actions into a scannable bulleted list with required params, so the density is justified. It is long, but nearly every line carries actionable information; minor tightening is possible in the action list.

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 13-parameter multi-action tool with no output schema and no annotations, the description supplies the return shape (source JSON with id, parentId, kind, status, revision, data), the error contract (409, 422), and per-action requirements. Nothing essential for correct invocation appears 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 0% for 13 parameters, yet the description maps every action to its required arguments (list→squad_id, get→source_id, create→squad_id+name+provider_type+base_url, etc.) and fully specifies the nested MetricQuery keys in camelCase with their allowed values. This more than compensates for the empty schema descriptions.

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

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

Opens with a specific verb+resource ('Manage measurement sources: squad-owned connections to pull providers') and immediately differentiates itself from sibling tools like polaris_measurement_providers and polaris_measurement_producers by scoping to squad-owned provider connections. An agent can identify the tool's domain 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?

The lifecycle sentence ('create → DRAFT, then check_connection must succeed, then activate') tells the agent the required ordering and prerequisites for each action, and each action lists its required parameters. It does not explicitly name alternative sibling tools to use instead, so it falls short of a 5.

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

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

With no annotations present, the description carries the full burden and does so well: auth model (X-API-Key, no Google login), synchronous evaluation, idempotency via producerId+externalRunId, the `replayed: true` duplicate signal, 409 on non-active version, and batch 207 per-item semantics where failures don't abort. This is rich beyond what any structured field provides.

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-loads the purpose and auth model, then organizes actions and the submission payload into scannable bullets. It is long but nearly every line is load-bearing for a two-action ingest tool with an opaque payload; minor trimming is possible.

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?

No output schema and no annotations, yet the description covers return behavior (recorded evaluation, replayed flag, 207 per-item statuses) and error conditions. An agent has everything needed to construct a valid submission and interpret the response.

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 0% and all four parameters are opaque objects/strings, so the description must compensate fully. It documents which params each action needs and details the `submission` object's required and optional camelCase keys (including nested measurements structure and constraints like RFC 3339 UTC and maximum observation age), which the schema alone does not convey.

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 ('Push measurements for evaluation') and pins the scope to the ACTIVE fitness-function version. It also names the two ingest actions (submit, submit_batch), making it clearly distinguishable from sibling evaluation/measurement tools.

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 per-action required parameters and the conditions that select each one (submit vs submit_batch), plus the 409 behavior against non-active versions. It doesn't explicitly name sibling tools as alternatives, but the when-to-use guidance for each action 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?

With no annotations, the description carries the full burden. It usefully discloses that create registers the squad ACTIVE and that transfer preserves ownership of everything the squad owns — meaningful mutation semantics. However, it omits what happens to resources in the source tribe post-transfer, permission requirements, reversibility, and any return/pagination 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?

Front-loads the purpose, then presents a scannable action/parameter list, then the object shape. Nearly every line earns its place, with only minor redundancy between the action list and the Squad JSON.

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 4-action, 10-param tool with no annotations and no output schema, the description supplies the action map, required params, mutation behavior, and an inline Squad JSON shape to substitute for the missing output schema. Only error/pagination semantics are left unstated.

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 0%, so the description must compensate, and it does: it binds each action to its required params (list→tribe_id, get→squad_id, create→tribe_id+name, transfer→squad_id+destination_tribe_id) and notes the optional mission/reason/limit/cursor/all_pages. This covers the large majority of the 10 params, though it does not explain reason or mission formatting.

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 the resource precisely — 'squads, the owning unit of fitness targets, sources, producers, and fitness functions' — which pins down what a squad is in the domain model. The action list enumerates the concrete verbs (list/get/create/transfer). It does not explicitly contrast itself with the polaris_tribes sibling, keeping it 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?

Each action is documented with its required parameters, which effectively tells the agent when each action applies (e.g. 'list: tribe_id', 'transfer: squad_id + destination_tribe_id'). This is strong per-action routing. It stops short of naming when NOT to use an action or pointing to a sibling alternative.

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

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

With no annotations, the description carries the full burden and does well: it discloses that 'archive' is a soft delete ("tribe stays queryable, status becomes ARCHIVED"), that lists are cursor-paginated with a returned nextCursor, and that 'overview' reads the Insights read model. Auth requirements and rate limits are unstated, keeping it out of the top band.

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 one-line purpose followed by a compact action/parameter table and a single-line JSON shape. Every sentence earns its place. Minor cost is that the Tribe JSON shape line is dense, but it is load-bearing given there is no output 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 five-action polymorphic tool with no annotations and no output schema, the description covers the action semantics, the mutation side effect of archive, the pagination contract, and the return object shape. Missing only edge cases such as error behavior or permissions on create/archive.

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 0% across 8 parameters, so the description must compensate and it does: it maps every parameter to the action that consumes it (list: limit/cursor/all_pages; get/archive/overview: tribe_id; create: name/description; archive: reason), states which are optional, and even gives the limit range (1-200). This is meaning fully beyond the bare 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 concrete verb+resource and, crucially, defines the resource's place in the topology ("the topology level that groups squads"), which implicitly distinguishes it from the polaris_squads sibling. The action enumeration reinforces the scope. It falls short of 5 because it never names the sibling it is not.

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 action list with required parameters gives clear task-level routing inside the tool, so an agent knows which action to pick. However, there is no guidance on when to prefer this tool over polaris_squads or polaris_insights (the 'overview' action reads the Insights model), and no prerequisites are stated.

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

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

With no annotations, the description carries the full behavioral burden and does so richly: the state machine (PROPOSED|APPROVED|REJECTED|REVOKED), the rule that only APPROVED unexpired waivers influence dispositions, the 409 on deciding twice, and the temporal constraint that expiresAt must be in the future and after startsAt. These are exactly the non-obvious traits an agent needs.

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 actions and required parameters, then a structured JSON shape. Nearly every sentence is substantive, though the trailing Waiver JSON block and state enumeration make it dense; a touch long, but well organized and free of 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 10-parameter, two-action mutation tool with no annotations and no output schema, the description supplies the missing pieces: required params per action, state transitions, idempotency/conflict behavior, and the returned object shape. Nothing an agent needs to call it correctly is absent.

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 0%, so the description must compensate, and it does: it maps every one of the 10 parameters to its action (fitness_function_id+reason for propose; waiver_id+decision for decide) and adds meaning beyond the schema, such as criterion_keys defaulting to all criteria and the RFC 3339 / future-date constraints on the timestamps.

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 ('Manage waivers') and immediately defines what a waiver is. It then distinguishes the two sub-actions (propose vs decide) with their distinct required parameters, so an agent can tell which action to invoke. The resource (waivers) is clearly distinct from siblings like polaris_fitness_functions.

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 per-action conditions: propose 'enters state PROPOSED; only takes effect on approval,' decide explains approve/reject/revoke semantics, and criterion_keys says 'omit for all.' This is strong within-tool guidance, though it does not route between this tool and sibling tools (e.g., when a waiver is preferable to a fitness_function edit).

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