company_employment_requestsPending requests to join a company. A company admin sees everyone waiting
on their door; anyone else sees only their own outstanding applications.
This is where the request_id for company_decide_employment_request
comes from.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, 1-based. | |
| page_size | No | Results per page (max 100). | |
| company_id | No | Only show requests for this company. |
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 meaningful behavioral detail beyond that: admin vs. non-admin visibility scoping and that the returned request_id feeds into a decision tool. This goes beyond what annotations alone would tell an agent.
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 three short sentences, each adding distinct value: what the tool lists, role-based behavior, and where the returned request_id is used. There is no redundancy or filler. The most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with no required parameters and full schema coverage, the description is nearly complete. It explains the core behavior and the role of the request_id, which is the main integration point. Since there is no output schema, slightly more detail about return fields could help, but the description is sufficient for correct invocation.
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 parameters page, page_size, and company_id are already fully documented in the schema. The description does not add new parameter-level meaning, but it does imply that company_id narrows results to a specific company. This matches the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as listing pending employment requests, with a specific resource (company employment requests) and a clear role-based scope: admins see all pending requests, others see only their own. It distinguishes itself from sibling tools like company_employees or company_roster by focusing on pending requests, though it does not explicitly name alternatives.
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 provides clear context on when to use the tool: to view pending employment requests, with different behavior depending on admin vs. non-admin status. It also points to a downstream use case (obtaining request_id for company_decide_employment_request), which helps an agent understand its role in a workflow. It does not explicitly mention when not to use it or name alternatives, but the usage context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Tools are grouped by domain prefix and mostly target a distinct resource, but there are several near-overlapping read clusters — notably whoami/event_roles/event_my_membership (all answer 'what roles at event X'), submission_get/submission_page, team_open_roles/team_seeking_members, and company_employees/company_roster. The descriptions do an exceptional job of steering ('use this, not that'), so misselection is unlikely, but the sheer number of such pairs keeps this from a 5.
The dominant domain_prefix + noun/verb pattern (event_, team_, submission_, company_, article_) is consistent and readable. Deviations: list_api_endpoints/list_capabilities invert the word order (verb-first) versus event_list/submission_list elsewhere, search and whoami carry no domain prefix, account_how_to_sign_in is a phrase, and read verbs vary between get/list/browse/page/preview.
60 tools is far beyond the 25+ threshold, and the surface is purely read-only — the breadth comes from extremely granular views (22 event_* tools) and many singleton catalogs (event_cities, event_types, event_background_images, article_languages, tag_list, tech_list, company_vacancies) plus six meta/informational tools. The domain is genuinely broad and every tool is distinct, so it reads as heavy rather than chaotic, but the count is still excessive.
The set contains zero write tools — no create, update, or delete anywhere — yet the descriptions repeatedly direct callers to absent tools: event_create, event_set_branding, event_add_sponsor, event_submit_registration_answers, invite_join, team_post, team_assign_role, team_remove_member, company_fire_employee, account_export_data, and more. An agent following the descriptions will call nonexistent tools and fail. The read/browse coverage is very thorough, but the complete absence of the write side (which the descriptions themselves treat as existing) is a significant gap.