--- name: shapes-essentials description: "How to use the Shapes HR connector well and safely: confirm the signed-in account and its visibility first, choose between overlapping employee, field, reporting-chain and aggregation tools, keep result sets small, handle permission and empty-result cases, and treat HR data as sensitive. Use when the user first asks an HR question with Shapes, asks what Shapes can see or do, or gets an unexpected or empty answer from Shapes." --- # Use the Shapes connector well Shapes holds sensitive HR data: names, job titles, reporting lines, time-off, reviews, attendance and personal fields such as date of birth. Your job is to answer the question asked, from the smallest correct slice of that data, and to say clearly what you could and could not see. Every tool in this connector is read-only, but the information itself is still confidential, so handle it with care. ## 1. Confirm who is asking and what they can see Before any analysis, call `get_current_employee` to learn whose profile the session belongs to. Note the account's office, team and job, since those often decide what the user is trying to ask ("my team", "our office"). Permissions carry over from the signed-in Shapes account. The same question can return different results for different people. Say so whenever a result looks incomplete: a missing team, a missing review cycle or an empty survey may mean "not visible to you", not "does not exist". Never present a partial view as the whole company. If the user's question needs data from another account, workspace or scope, stop. Switching the active account or connection is a change of state, so wait for the user's explicit yes before doing it, and say which account you would switch to and why. ## 2. Choose the right tool family before calling anything The connector has overlapping tools. Pick the family by the question's shape: - **Who is this person, or who matches these criteria?** Use the employee tools (`get_employees`, `get_employee`). Narrow by name, title, office or team. - **What custom field exists, and what values does it hold?** Use `get_employee_field_types` first to learn the field names, then `get_employee_field_values`. Do not guess field names. - **Who reports to whom?** Use `get_reporting_chain` and `search_in_hierarchy`, not repeated employee lookups. - **How many, what share, what breakdown?** Use the `*_insights` tools (`employee_insights`, `performance_review_cycle_insights`, `performance_review_participation_insights`, `time_away_insights`). They return aggregates, so you do not need raw rows, and they keep personal detail out of the conversation. - **A count across a whole population, from raw rows?** Pull the rows only when the insight tool cannot answer the question, and say you did so. Reach for the aggregate first. A workforce breakdown should not need a list of every employee. ## 3. Keep result sets small and specific Ask for the fields you need, filter by the criteria the user gave, and page through results rather than fetching everything. Prefer a summary of 20 matches with a count to a dump of 400 names. If the population is large, report the count, the criteria used, and offer to narrow it or to aggregate instead. Never paste personal fields (date of birth, personal contact, sensitive custom fields) into a reply unless the user has a clear, legitimate reason and asked for them. ## 4. Handle empty results and errors honestly An empty result has several possible causes: no match, a typo in the criteria, a field that is not populated for most people, or data the account cannot see. Before concluding "none", check the spelling and try one broader filter. Report what you tried. If a tool returns a permission error, say which scope blocked the call and what the user would need, and do not work around it by guessing values. If a call fails partway through a multi-step question, say which part is missing rather than presenting a total as complete. ## 5. Read-only means read-only for the answer, not for the user's decisions Every listed tool reads data. Nothing you do here changes an HR record, approves leave, or submits a review. If the user asks you to approve a booking, edit a balance, send a reminder or change a policy, Shapes cannot do it through this connector. Say so and point them to the HR system. ## Common patterns and traps - **Name collisions.** Two people share a name. Confirm by title, office or manager before reporting anything about "John Smith". - **Stale or sparse fields.** A custom field may be blank for most employees. A 3% breakdown can reflect poor data entry, not reality. Report the coverage with the figure. - **Counting people versus bookings.** One employee can have several time-away bookings; a count of bookings is not a count of people off. Say which one you counted. - **Invisible populations.** A team lead may see their team but not the whole company. Results for "the whole company" are only as complete as the signed-in account's view. - **Sensitive combinations.** Pairing a named person with absence reasons, health-related leave or performance status is a privacy risk even when each piece is visible. Ask why the user needs it and keep it to the minimum. - **Assuming a tool exists.** Some tools in the wider product may not be in the list above. Use only the tools you have been given. ## Output ``` Account: — scope: Question: Tools used: Answer: Coverage: