Namely MCP by usefulapi

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

Annotations only flag destructiveHint=true; the description adds what actually makes it destructive (email_all emails every active employee and cannot be undone) and the permission requirement. It also discloses that the post is visible to every employee, which matters for a mutation an agent may invoke casually.

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 purpose, then format, then the dangerous parameter with its warning. Dense but every clause carries information; only the emphasis styling on 'ALSO EMAILS' is stylistic overhead.

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-param mutation with no output schema and full schema coverage, the description covers audience, formatting, permission, and irreversibility. It stops short of saying what the call returns (e.g. an announcement or event id), which would help chaining or follow-up actions.

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 baseline is 3; the description adds real meaning beyond it, notably the markdown mention syntax [Full Name](/people/<profile_id>) and the fact that is_appreciation acts on mentioned profiles. It still doesn't say what a valid profile_id looks like or where to obtain one.

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 (post an announcement) plus the exact scope and audience (company home feed, every employee). No sibling tool covers announcements, and the description makes the audience blast explicit, so an agent can select it unambiguously.

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 an explicit when-not rule for the risky path: email_all 'set it only when the user explicitly asks'. It doesn't discuss alternatives for narrower communications (comments, events), but there are no competing announcement siblings, so the missing piece is minor.

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 carry destructiveHint=true, so the description is doing the disclosure work: it names the acting identity (the token's user), the audience (employees who can see the event), and the transport endpoint POST /events/{id}/comments. It does not cover rate limits, permission failures, or whether the comment can later be edited or removed, and it does not explain the destructiveHint classification.

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 sentences plus an endpoint tag, with the primary action and side effect front-loaded and formatting guidance trailing. No filler or restatement of the tool 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 two-parameter write tool with no output schema and high schema coverage, the description supplies what matters: side effects, identity, audience, and rich-text formatting. It omits only error/permission behavior and what the response returns (e.g., a comment id), 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 coverage is already 100%, so the baseline is 3, but the description adds real value beyond the schema by documenting supported markdown and the mention syntax '[Full Name](/people/<profile_id>)', which is not expressible in the plain string parameter. The event_id provenance hint reinforces what the schema already says rather than extending it.

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+resource ('Add a comment to a feed event') and implicitly separates itself from the read-side sibling namely_list_event_comments and from namely_create_announcement. An agent can tell exactly what this creates 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?

It gives the operating context: the comment is posted as the token's user, visible to everyone who can see the event, and event_id must come from namely_list_events. It does not explicitly name an alternative (e.g., read comments via namely_list_event_comments) or state when not to comment, so it stops short of full 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?

With readOnlyHint=true already covering the safety profile, the description adds real context: the response embeds the linked profiles (members) and the call maps to GET /groups/{id}. It does not cover behavior for a missing/invalid 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 payload detail up front, followed by the underlying endpoint as a secondary reference. 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 one-parameter read with no output schema, the description tells the agent what comes back (a group plus its member profiles) and the source of the id, which is enough to call it correctly. Error/not-found behavior is the only notable omission.

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 single id parameter is already documented with its provenance. The description restates "by id" without adding format or syntax detail, 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 ("Get one group by id") and adds that the linked profiles are included, which is exactly what separates it from a plain group lookup. It does not name a sibling like namely_list_groups explicitly, so it falls short of full sibling differentiation.

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: fetch a single group when you already have an id (the schema even points at namely_list_groups as the id source). There is no explicit when-to-use/when-not or statement about preferring namely_list_groups for enumeration.

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 already declares the safety profile, so the description's remaining burden is light; it adds real value by declaring which fields come back (name, email, job title, manager, access role) and citing the exact endpoint, which tells an agent the token's identity is the subject. It doesn't mention failure modes for an invalid/expired token, which keeps 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?

Two compact sentences: the verb and subject first, the returned fields second, the API mapping last. No redundancy and nothing an agent needs is buried.

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 field list in the description effectively substitutes for one, and the endpoint gives grounding. For a zero-argument read, that is nearly complete; only token-failure behavior 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?

Zero parameters, so the baseline of 4 applies; there is nothing about the call signature left ambiguous. The description correctly frames the identity as derived from the token rather than from any argument, which is the one semantic point that matters 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?

A specific verb plus resource with a clearly scoped qualifier: "the profile of the user the connected token belongs to," followed by the concrete field list and the underlying API endpoint. It implicitly separates itself from namely_get_profile (which requires an id) and namely_list_profiles, 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?

The "connected token" phrasing implies when this applies (self-lookup vs. arbitrary profile lookup), but the description never states when to prefer this over namely_get_profile or namely_list_profiles, nor any exclusions. Usage is inferable rather than 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?

Annotations already establish readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: the returned fields depend on what the token may see and can include compensation and other sensitive HR data, which is an important disclosure for an agent handling the output.

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 dense but front-loaded sentence covering purpose and scope, followed by a short endpoint reference. No filler, and the sensitivity caveat sits in the same sentence rather than buried later.

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 burden of describing the return value, and it does so by enumerating the field families returned, including the token-dependent custom fields. The only gap is error behavior for an invalid or inaccessible id, which is a minor omission for a one-parameter read tool.

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 with 100% schema description coverage, so the schema already explains that the id is a Namely profile id from namely_list_profiles. The description only restates "by id" and adds no format or validation detail beyond the schema — baseline 3.

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 one employee's full profile by id") and enumerates the payload scope: personal/job data, manager, groups, teams, custom fields. That makes it clearly distinguishable from namely_list_profiles (many) and namely_get_group/namely_get_team (other resources).

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" plus the schema note that the id comes from namely_list_profiles implies the list-then-fetch pattern, but the description never explicitly says when to prefer this over namely_list_profiles or namely_get_me for the caller's own profile. Usage is implied rather than 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?

readOnlyHint=true already declares it as a safe read, but the description adds value the annotations don't: data is live, rows are positional lists rather than keyed objects, and results may contain sensitive HR data like salary history. It omits any note on result size limits or pagination for large reports, which matters for a tool that returns row sets.

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 sentences, each doing distinct work: what it does and returns, how to get the id, then a sensitivity warning plus endpoint. The core action and return shape are front-loaded with zero 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 appropriately compensates by explaining that the response contains columns and ordered row lists. The main residual gap is the lack of any statement about result volume or limits, which an agent would want before running a large report.

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 single parameter is documented only as 'Report id.', so the description's instruction to find the id in the report URL is genuinely additive provenance rather than a restatement. Nothing further is needed for a one-parameter tool, though the id format itself is still not characterized.

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 ('Run a saved Namely report by id') and immediately defines the return shape: columns and rows with each row a list in column order. That distinguishes it cleanly from the sibling list_* tools, which enumerate fixed resource types rather than executing saved reports.

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?

Tells the agent the report must be 'saved' and where to obtain the required id (the URL of the report in Namely), which is actionable context. It does not state exclusions or when a sibling such as namely_list_profiles would be preferable for a simple data pull, so it stops short of 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=true, so safety is covered. The description adds genuinely useful context beyond that by disclosing that the response embeds linked profiles (members), but says nothing about missing-id behavior, permissions, or payload size for large teams.

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 followed by the endpoint reference. Every phrase earns its place with no redundancy.

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-parameter read tool with annotations covering safety and a complete schema, the description supplies the one non-obvious fact an agent needs: the response includes linked profiles. No output schema exists, but the return shape is characterized briefly, so remaining gaps are minor.

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 single id parameter is fully documented in-schema, including its source (namely_list_teams). The description adds no further meaning about the id (format, accepted values) beyond what the schema 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 and resource ('Get one team by id') and adds scope detail that the tool returns the team with its linked profiles. It is distinguishable from namely_list_teams by the singular 'one team by id', though it does not name the 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?

Usage is only implied: 'by id' signals a single-record lookup versus the list siblings, and the schema notes the id comes from namely_list_teams. There is no explicit statement of when to prefer this over namely_list_teams or namely_get_group.

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 annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying REST path, which gives useful context about scope, but it says nothing about pagination, result ordering, or whether event comments can be empty.

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 operation front-loaded and no filler. The endpoint reference is mildly redundant, but harmless for API-aware agents.

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 whose annotations cover safety, the description is adequate. Because there is no output schema and the description does not say what the returned comments contain or how many come back, one gap remains.

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% for the single required event_id, and the schema itself already says the id comes from namely_list_events. The description adds no further meaning about format or constraints, 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 verb and resource are explicit: it lists comments on a feed event, which implicitly distinguishes it from the sibling namely_create_event_comment. However, it never names that sibling outright, so the agent has to infer the read-versus-write split.

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 is a single purpose statement with no explicit when-to-use or when-not-to-use guidance. The only routing hint, namely that event_id comes from namely_list_events, lives in the schema rather than in the description.

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 readOnlyHint=true already declaring safety, the description adds useful behavior: default ordering is newest-first and paging uses a cursor-style event id. It does not cover auth needs, what the payload contains, or whether filter combinations are restricted, so it adds moderate context only.

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 that front-loads the resource and scope, then the ordering and paging facts, with the API endpoint appended. Nothing 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?

All parameters are optional, annotations confirm a read-only operation, and there is no output schema to explain, so the description is largely sufficient. A short note on what a feed event object contains or auth expectations would close the remaining 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 coverage is 100%, so all five parameters are already documented; the description still reinforces the two paging parameters and clarifies that 'after' is an event id rather than a timestamp. It leaves the type, order, and profile_id filters entirely to 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 (List) and resource (events of the company home feed) and enumerates the concrete event kinds it returns, so the agent knows what data comes back. It doesn't explicitly distinguish itself from nearby siblings like namely_list_event_comments, leaving that separation to the tool names.

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?

Implies the browsing use case for the home feed and explains paging via 'limit and after (an event id)', but never says when to prefer this over alternatives or what preconditions apply. Usage is inferable rather than 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?

The readOnlyHint annotation already establishes this as a safe read, so the bar is lower. The description adds useful domain semantics ('every group belongs to one group type') and the underlying endpoint (GET /groups), but says nothing about result volume, pagination, or whether the group type appears inline versus requiring a separate lookup.

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 no filler, and the core action is front-loaded in the first phrase. The endpoint reference is minor but legitimately useful for debugging or correlating with Namely documentation.

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, schema-less, annotation-covered list operation this is adequately complete: it names the resource, its subtypes, and the underlying API route. The only meaningful omission is how groups relate to group types at call time (inline vs. separate fetch).

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. The description correctly implies no filtering inputs are available ('List all groups') rather than suggesting optional filters that do not 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?

The description uses a specific verb and resource ('List all groups') and adds domain context by naming what a group is (departments, office locations), which helps an agent map the concept. It distinguishes implicitly from the singular sibling namely_get_group, but never explicitly routes to it or to namely_list_group_types.

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: 'List all groups' signals a bulk read with no filtering, versus namely_get_group for a single record. There is no explicit when-to-use, when-not-to-use, or named alternative, and no mention of the related call namely_list_group_types that an agent would likely need.

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 read, so the description does not need to restate that. It adds mild value by mapping the tool to the underlying endpoint GET /group_types, but discloses nothing about result size, ordering, 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 zero waste, and the core purpose plus the disambiguating definition are front-loaded ahead of the API mapping detail.

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-parameter read with no output schema, the definition covers what the tool returns conceptually (the set of group-type containers). The main residual gap is that it does not hint at what fields each group type carries, which an agent might want since 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?

The tool takes zero parameters, so the baseline of 4 applies. The description correctly implies no filtering or input is required, matching the empty 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+resource ("List the group types") and disambiguates the concept with a parenthetical definition: containers of groups such as Department or Office. That effectively separates it from the sibling namely_list_groups, though it never names 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?

Usage is only implied: an agent can infer it should call this when it needs the taxonomy of group containers rather than the groups themselves. There is no explicit when-to-use, prerequisite, or reference to namely_list_groups as the 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?

readOnlyHint=true already declares this is a safe read, so the description carries a lighter burden. It adds the underlying endpoint (GET /job_tiers), useful for traceability, but says nothing about pagination, ordering, or completeness of the returned set.

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 followed by the endpoint reference — every element earns its place and the core purpose 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 zero-parameter read-only list with annotations covering the safety profile and no output schema, this is close to sufficient. Only the return shape / pagination behavior is unaddressed, which is a minor gap given the tool's simplicity.

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 compensate for; baseline 4 applies. 'List all' usefully confirms no filtering is available.

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 all job tiers') and adds a gloss — 'the levels that group job titles' — that meaningfully distinguishes it from the sibling list_job_titles. It does not explicitly name the sibling, so it stops 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?

'List all' implies an unfiltered enumeration with no parameters, which is a usage hint, but the description never states when to choose this over namely_list_job_titles or what to do with the result. Guidance is implied only.

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 read. The description adds the underlying endpoint (GET /job_titles) and the title-to-tier relationship, but says nothing about result size, pagination, ordering, or whether the full set is always returned unpaged.

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 purpose front-loaded and zero filler; the tier relationship and endpoint are each worth one clause.

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-parameter, read-only list with no output schema, the description gives enough to call it correctly and to understand the returned records relate to job tiers. Only pagination/ordering behavior is 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies no filtering arguments are needed.

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 all job titles') and adds the relational fact that each title belongs to one job tier, which distinguishes it from the sibling namely_list_job_tiers. It does not explicitly name that sibling as the alternative, so it stops 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?

The intent to retrieve the full job-title catalog is implied by 'List all', but there is no explicit when-to-use, when-not-to-use, or pointer to namely_list_job_tiers as the complementary call. Usage is inferable rather than 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds value by disclosing what the response contains — labels, sections, and the valid format of each value. The Namely API endpoint reference also aids debugging, though pagination or response shape details are absent.

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 sentences, front-loaded with the core purpose and the returned content, followed by the API endpoint. No filler or repetition.

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 parameters and no output schema, the description carries the burden of explaining the return value and does so at a useful level (labels, sections, valid value formats). It could go slightly further by noting the response is a flat field list usable to interpret namely_get_profile output.

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 to document and the baseline of 4 applies. The description correctly implies a company-scoped, unfiltered listing with no inputs required.

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 a precise resource (employee profile fields as configured at this company), including that both standard and custom fields are covered. The resource is clearly distinct from siblings like namely_get_profile and namely_list_profiles, though no sibling is named 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 implied rather than stated: an agent can infer this is a schema/metadata discovery call, useful before reading or updating profile values. There is no explicit when-to-use, when-not, or pointer to a sibling such as namely_get_profile for actual values.

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?

Beyond readOnlyHint=true, it discloses a rate limit (100 requests per minute), warns that the full record exposes sensitive HR data like compensation and addresses, and explains the pagination termination signal. These are precisely the behavioral facts annotations cannot carry.

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 in the first clause, followed by return shape, format choice, pagination, and API/rate-limit details. Every sentence carries information, though the single dense paragraph could be split for scanability.

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 still supplies return shape ({profiles, meta:{count}, linked}) and pagination semantics. An agent has everything needed to call and iterate 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 100%, so baseline is 3, but the description adds meaning by spelling out what format=short returns (ids, names, email, status, job title) and that full includes every visible custom field. Other parameters such as reports_to and the exact-match filters are left to 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?

Specific verb+resource (list employee profiles) with scope stated: includes active, pending and inactive unless filtered. It is clearly distinguishable from the sibling namely_get_profile, which fetches a single profile.

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 selection guidance: use format=short for a smaller record versus full for all custom fields, and notes an empty page means the end of pagination. It never explicitly names when to prefer namely_get_profile or how to combine filters, so it stops short of full alternative 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds that results include team categories and names the underlying endpoint, but says nothing about pagination, result size limits, or ordering — relevant for an unfiltered collection listing.

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 sentences with no waste. The endpoint reference is mildly redundant but harmless context.

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-param list tool with an annotations-only safety profile and no output schema, the definition covers the essentials but omits pagination behavior and any notion of result volume — gaps that matter when listing an entire collection.

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 clarify; the baseline applies. No misleading parameter claims are present.

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 (list) and resource (teams) plus a note that team categories are included in the result. It does not distinguish itself from the sibling namely_get_team, so an agent must infer the collection-vs-single distinction from the name alone.

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?

"List all teams" implies a collection read, and the presence of namely_get_team suggests the alternative, but the description never states when to use one over the other. Usage is only implied, not guided.

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?

Adds real context beyond annotations: the write is to live HR production data, and status=pending carries a dependency on personal_email. With destructiveHint=true declared, the agent already knows mutations are risky; the description doesn't cover permissions/authorization or rollback 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?

Four dense, front-loaded sentences with zero filler: scope first, then the write warning, then the patch instruction, then the conditional constraint. Every sentence 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 9-parameter mutation with a nested job_title object and no output schema, the description covers scope, write risk, patch semantics and the one conditional constraint. It leaves out how invalid job titles are handled and what a successful response contains, but the rich schema compensates for most of that.

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 descriptions exist for every parameter, so the schema carries the burden and the baseline is 3. The description does add one genuinely useful cross-field rule (pending requires personal_email) that the schema only states per-field, but it adds nothing further on job_title nesting or id sourcing.

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 verb (change) and resource (employee profile) and enumerates the affected field families, which cleanly separates it from the read siblings (namely_get_profile, namely_list_profiles). The API endpoint (PUT /profiles/{id}) reinforces the exact operation.

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 the fields to change" gives clear patch-style usage and "WRITES live HR data" signals this is not a dry run. It stops short of explicitly stating when not to use it (e.g. bulk updates or profile creation), so no full alternative routing is given.

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