folk

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

Annotations provide only destructiveHint=true, so the description carries nearly the full burden and adds nothing about side effects, required auth, or duplicate handling. The REST endpoint reference is the sole extra detail and does not describe observable behavior beyond annotations.

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 two short sentences are front-loaded and waste no words. However, the extreme brevity comes at the cost of coverage rather than being genuinely efficient for a 13-parameter tool.

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 complex 13-parameter creation tool with nested objects and no output schema, the description omits return shape, defaults, and any behavioral caveats. Annotations are minimal, so the definition leaves meaningful gaps for an agent to fill.

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

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

Schema description coverage is 100%, with all 13 fields including nested groups and the employeeRange enum documented inline, so the schema does the heavy lifting. The description adds nothing beyond repeating that `name` is required, making the baseline 3 appropriate.

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 ('Create a new company'), which cleanly separates it from sibling create tools for notes and people. It lacks any explicit comparison or scoping language, but the resource is unambiguous.

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

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

There is no guidance on when to use this versus folk_update_company or the other create tools, and no prerequisites, permissions, or idempotency/duplicate-handling notes are given. The only directive is a restatement that `name` is required.

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 flag destructiveHint=true, so the safety profile is partly carried by structured data. The description adds only the REST endpoint mapping; it says nothing about permissions needed, whether re-creating on a missing entity fails, rate limits, or what happens with parent_note_id replies. A create/write tool with such thin behavioral disclosure warrants a low score.

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 no filler and the core purpose front-loaded before the API mapping. It is efficiently sized, though the REST endpoint note is of marginal value to an agent.

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

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

For a 4-parameter mutation tool with no output schema, the description covers only the bare purpose. It omits behavior around private vs public visibility implications and threaded replies via parent_note_id, leaving gaps that the schema alone only partially fills.

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

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

Schema description coverage is 100%, so the schema documents all four parameters including the visibility enum and parent_note_id semantics. The description adds no parameter-level meaning beyond what the schema already provides, 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 ('Create a note') plus the scoping detail that the note attaches to an entity (person/company), which distinguishes it from sibling reads like folk_get_note and folk_list_notes. It does not, however, differentiate itself from other create tools such as folk_create_person/folk_create_company.

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

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

There is no guidance on when to use this tool versus alternatives, no mention of prerequisites (e.g. the entity must already exist), and no exclusions. The agent is left to infer everything about invocation context.

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 flag destructiveHint=true, so the safety profile is partly covered. The description adds 'All fields are optional' and the REST endpoint, but says nothing about duplicate handling, whether an existing person is merged/linked, or auth requirements — meaningful gaps for a create-with-linking tool.

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

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

Three short sentences, front-loaded with the action. The REST endpoint line is arguably inert for an agent but cheap, and nothing is padded or redundant.

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

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

For a 14-parameter tool with nested objects and no output schema, the description is thin: it never says whether the new person's id is returned, nor how the company/groups linking behaves on creation. It is minimally viable but leaves an agent guessing about outcomes.

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

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

Schema description coverage is 100% across all 14 parameters, including the {id}-vs-{name} company union, so the schema carries the semantics. The description's only substantive contribution is confirming that none are required, which is already implied by the empty required list. Baseline 3 is appropriate.

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 ('Create a new person (contact)') with no ambiguity. Sibling differentiation is only implicit — it relies on the reader inferring create-vs-update/get from the name — but the purpose itself is unmistakable.

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

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

'All fields are optional' gives one useful precondition, but there is no guidance on when to use this versus folk_create_company or folk_update_person, nor any exclusions (e.g. duplicates). No context for choosing this tool over alternatives.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered without description help. The description adds only the REST endpoint mapping, with no mention of return shape, error behavior for missing ids, or auth needs; with annotations carrying the safety burden, this is adequate but thin.

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

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

Two short sentences, front-loaded with the operation and followed by the endpoint mapping; there is no filler and every clause carries information.

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

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

For a simple single-resource read with no output schema and readOnlyHint already set, the description covers what the tool does and how it maps to the API. The only missing piece is any notion of error/not-found behavior, which is minor for this complexity level.

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

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

Schema description coverage is 100% and the single 'id' parameter is already documented in the schema. The description restates 'by id' without adding format, source, or lookup semantics, so the baseline of 3 for schema-covered parameters applies.

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

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

States a specific verb and resource ('Get a single company by id') and includes the underlying REST mapping (GET /v1/companies/{id}), so the operation is unambiguous. It does not explicitly contrast with the sibling folk_list_companies, but 'a single company by id' implicitly separates it from a list 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?

The description gives no explicit when-to-use or when-not-to-use guidance and never names an alternative. An agent can infer it is for fetching one known company, but choosing between this and folk_list_companies or folk_get_person is left entirely to inference.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds useful context that the lookup is keyed to the API key (i.e., auth-derived identity), but says nothing about failure behavior when the key is invalid or rate limits. Adequate but not rich.

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

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

Two tight sentences with the core purpose front-loaded and the endpoint reference appended as supporting detail. No filler or redundant restatement of the title.

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

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

For a no-parameter, read-only identity lookup this covers what an agent needs to select and invoke it. Without an output schema, a brief note on which user fields are returned would have made it fully self-contained.

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 since no parameter semantics 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 ('Get') and resource ('the user'), scoped precisely to the user tied to the current API key, which cleanly distinguishes it from the sibling folk_list_users. The REST endpoint reference (GET /v1/users/me) pins down 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?

The scoping phrase 'associated with the current Folk API key' implies the use case (resolving the authenticated identity) but never states when to prefer this over folk_list_users or folk_get_person. Usage is inferable rather than explicit, with no exclusions named.

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

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

readOnlyHint=true already declares the safety profile, so the description's remaining burden is light. It adds the REST endpoint mapping but nothing about not-found behavior, error shape, or what fields a note returns; with annotations covering the read-only nature, a 3 is appropriate.

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 action and free of padding. The REST endpoint mapping is mildly redundant with the tool name but takes no extra parse effort.

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

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

For a single-parameter read tool with annotations covering safety, a 100%-covered schema, and no output schema to explain, the description is essentially sufficient. Only minor gaps (not-found semantics, pagination-free confirmation) remain.

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

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

Schema description coverage is 100% for the single required "id" parameter, and the schema already states "The note id." The description adds no format, prefix, or sourcing detail beyond that, so the baseline 3 applies.

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

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

The description gives a specific verb+resource ("Get a single note by id") and the singular scope implicitly separates it from folk_list_notes. It does not explicitly name a sibling or a disambiguation edge case, 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?

Usage is only implied: the agent infers it should call this when it already has a note id. There is no explicit when/when-not guidance or pointer to folk_list_notes for discovery, so this is minimum-viable.

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 for free. The description adds essentially nothing beyond that — no error behavior (e.g., unknown id), no permission requirements, no indication of what the response contains. The REST line merely restates the operation.

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 core purpose. The 'Folk REST: GET /v1/people/{id}' line adds minor API-reference value but is largely redundant with 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 simple single-param read with annotations covering readOnly and no output schema, this is minimally adequate. Since no output schema exists, the description would ideally hint at what a person record returns or how a missing id behaves, which it does not.

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 id parameter with 100% schema description coverage, so the schema already documents it fully. The description adds no format, encoding, or example detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb (get) and resource (single person/contact) keyed by id, which is unambiguous against folk_list_people and the other get_* tools. However, it never explicitly contrasts itself with folk_get_current_user or folk_list_people, so it's clear but not sibling-differentiating.

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 no when-to-use context, no prerequisites, and no mention of alternatives such as folk_list_people or folk_get_current_user. Usage is only inferable from the tool name itself.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is established. The description adds that results are cursor-paginated and filterable, which is genuinely useful context, but says nothing about max page size behavior, ordering, or what an empty result means.

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 fragments, front-loaded with purpose followed by capability and endpoint provenance. Nothing is wasted, though the endpoint reference is of marginal value to an agent choosing a tool.

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

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

For a read-only list tool with no output schema, the description covers the essentials: cursor pagination and structured filtering, with the schema supplying full parameter detail. It is slightly thin on result shape, but annotations and schema carry most of the load.

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

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

Schema description coverage is 100%, so all four parameters (limit, cursor, filter, combinator) are fully documented in the schema, including the filter expansion syntax and the nextLink cursor source. The description adds nothing beyond this, 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+resource ('List/filter companies') and even names the underlying REST endpoint, so the agent knows exactly what operation is performed. It does not explicitly contrast itself with non-list siblings like folk_get_company, but no ambiguity arises from the list-tool family.

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 infers this is the tool for enumerating companies, and the pagination/filter mention hints at when it fits. There is no explicit when-to-use vs alternatives (e.g., use folk_get_company for a single record) and no exclusions.

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 is a safe, non-mutating read. The description adds the underlying REST route (GET /v1/groups), which is mildly useful context but not behavioral disclosure; it says nothing about pagination behavior or result shape beyond what the schema's cursor field implies.

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

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

Two short sentences, zero filler, with the core purpose front-loaded before the API-route detail. 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 simple read-only list tool with annotations and a fully documented schema, this is close to adequate, but with no output schema the description could have said what a returned group contains (e.g., id/name) since those ids are the stated reason to call it.

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

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

Schema description coverage is 100%, with both limit and cursor fully documented in the schema. The description adds no parameter guidance, so the baseline of 3 applies since the structured data carries the full burden.

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 groups in the Folk workspace") and even explains why an agent would want it ("ids needed to place people/companies"). It does not explicitly contrast itself with the many sibling list_* tools, but the resource is unambiguous enough that confusion is unlikely.

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 parenthetical implies the use case: fetch group ids before placing people or companies. There is no explicit when-to-use vs. when-not statement and no mention of alternatives, so usage is inferred 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 filter scoping and the underlying REST endpoint, but says nothing about pagination behavior, default result counts, or what a call returns when there are no notes.

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, with the core list-and-filter capability front-loaded. The trailing 'Folk REST: GET /v1/notes' is mildly redundant but does give an implementation anchor; nothing is verbose.

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?

There is no output schema, so the description carries some burden for return shape, and it does not describe the response envelope, pagination.nextLink, or default page size (only the cursor param hints at paging). Adequate but with clear gaps for a 6-param list 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?

Schema description coverage is 100%, so the 6 parameters (limit, query, cursor, entity_id, created_after, created_before) are fully documented in the schema. The description restates the filter categories without adding format, default, or boundary detail beyond what the schema already provides — 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?

The description states a specific verb (List) and resource (notes) and enumerates the available scoping dimensions (entity, full text, creation date). It does not explicitly distinguish itself from siblings like folk_get_note or folk_create_note, though the name and verb make the split reasonably obvious.

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

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

Usage is implied by the phrase 'optionally scoped to...' which signals the tool is the broad retrieval path, but there is no explicit when-to-use/when-not guidance or naming of an alternative (e.g., folk_get_note for a single note). An agent can infer intent but is given no routing rules.

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 usefully adds that pagination is cursor-based and filters are supported, but says nothing about default page size behavior, rate limits, or what the return shape looks like – modest added value beyond structured fields.

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

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

Three short sentences, front-loaded with the core purpose. Tight overall, though the trailing 'Folk REST: GET /v1/people' line adds little beyond implementation trivia.

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

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

For a read-only list tool with fully documented parameters and a trivial nested filter object, the description is adequate; the only meaningful omission is the return/pagination shape, which is partially implied. No output schema exists, so return values are not strictly required to be explained.

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

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

Schema description coverage is 100%, so limit, cursor, filter, and combinator are all fully documented in the schema. The description only echoes 'cursor pagination' and 'structured filters' without adding syntax or format detail, so the schema baseline of 3 applies.

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

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

States a specific verb (List/filter) and resource (people/contacts), and names the REST endpoint it wraps. An agent can easily distinguish it from folk_list_companies or folk_list_notes by resource, but the description never explicitly routes against the get_person/create_person/update_person siblings.

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

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

The mention of cursor pagination and structured filters implies the read/list use case, but there is no explicit when-to-use guidance and no stated alternative (e.g., 'use folk_get_person for a single contact'). Usage is left to inference.

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's obligation is reduced. It adds the underlying REST call (GET /v1/users) and the returned field set, but says nothing about pagination behavior, rate limits, or result size — the schema covers cursoring but not the behavior around it.

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

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

A single front-loaded sentence with zero padding, and the returned-field list sits right after the resource. The trailing REST path restates what the verb already conveys, which is mildly redundant but harmless for an agent that reasons over HTTP endpoints.

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?

This is a simple, zero-required-parameter read with no output schema, so the description's listing of returned fields (id, name, email) usefully compensates for the absent return contract. It is nearly complete, needing only a word on pagination or result ordering.

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

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

Schema description coverage is 100%: limit's range/default and cursor's nextLink convention are both fully documented in the schema. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

Names a concrete verb and resource ('List users in the Folk workspace') and enumerates the returned fields (id, name, email), which sets it apart from the note/company/person siblings. It does not explicitly distinguish itself from the closest sibling, folk_get_current_user, 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?

'Useful for resolving owner ids' implies the intended scenario but gives no explicit when-to-use rule, no exclusions, and no named alternative (e.g. get_current_user vs a full user list). Usage is inferred 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 only supply destructiveHint=true; the description adds two genuinely behavioral facts: this is a partial (merge) update, and list-valued fields REPLACE rather than append — real data-loss context that the annotation alone does not convey. It also cites the underlying REST endpoint (PATCH /v1/companies/{id}) for provenance. It omits permissions/auth needs and error behavior, so not a 5.

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

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

Three short sentences, front-loaded with the core action followed by the two behaviors that matter most, then the API reference. 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?

For a 14-parameter mutation tool with no output schema, the description covers the critical semantics an agent needs (partial update, list replacement). It stops short of naming auth/permission requirements or what happens when the id does not exist, minor gaps for an otherwise tight definition.

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

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

Schema description coverage is 100% across all 14 parameters, so the schema already documents each field, including the per-field 'Replace the company's ...' notes. The description's blanket rule about list replacement restates what the schema says per property, so it adds little beyond the baseline.

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 (update) and resource (company) with the qualifier 'existing', which cleanly separates it from folk_create_company and, by resource, from folk_update_person. It never names a sibling directly, but the scope is unambiguous from the description 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?

The description explains the update semantic ('only provided fields are changed') but gives no when-to-use framing, no prerequisites, and no exclusions or alternative tools. Usage is implied by the name 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 destructiveHint=true, and the description earns its keep by explaining exactly what is destructive: only supplied fields change, while list-valued fields (emails, phones, groups, companies) REPLACE rather than append. That is the key non-obvious behavior behind the hint, though it stops short of covering permissions or response 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 short sentences, front-loaded with the core action and the most important caveat (replacement semantics), with 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?

For a 15-parameter mutation tool with no output schema, the description covers the partial-update contract and the destructive replacement rule, which is what an agent most needs. Auth/error expectations are the only real omissions.

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

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

Schema description coverage is 100%, so all 15 parameters are already documented in the schema, including per-field 'Replace the ...' wording. The description only generalizes that rule for the list fields, adding little beyond what is already structured.

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 ('Update fields on an existing person') and immediately scopes it as a partial update, which cleanly distinguishes it from the create_person sibling. The REST mapping (PATCH /v1/people/{id}) removes any ambiguity about the 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?

The description implies the tool applies to already-existing people and clarifies partial-update semantics, but it never names an alternative (e.g., use folk_create_person for new records) or states when-not to use it. Usage is inferable rather than explicitly guided.

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