Foundaree

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

Annotations only declare the mutation shape (readOnlyHint=false, openWorldHint=true, idempotentHint=false); the description supplies the real behavioral context an agent needs: the recipient sees the request on Foundaree and calls back, nothing is confirmed until then, and payment happens directly between the parties. It also discloses the return value (`bookingId`) and the verification path via `check`, which annotations cannot express.

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?

Dense but front-loaded: purpose and examples come first, then preconditions, confirmation gate, behavioral outcome, and return value in a logical order. Minor redundancy in "only with the user's OWN name and phone number, which they gave you: never guess or reuse another number" costs a point but every sentence is actionable.

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 outbound request tool with no output schema, the description covers the confirmation flow, the asynchronous acceptance model, payment boundaries, and what is returned. Nothing an agent needs to call it safely and correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds provenance and constraints the schema doesn't, namely that `kind` and `username` come from a prior `find` result and that `name`/`phone` must be the user's own supplied values, never reused. It stops short of clarifying optional fields like `area` or `items` any further.

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

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

Opens with a specific verb and resource ("Send a booking or order to one person or business on Foundaree") and backs it with three concrete user-utterance examples. It also distinguishes itself from sibling tools by pointing to `find` as the source of `kind`/`username` and to `check` as the follow-up step.

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 explicit when-to-use ("only when the user asked to book"), a hard precondition ("A business must have `bookable: true`"), and a required confirmation gate ("tell the user what you will send and to whom, and get their yes"). It also names when not to proceed by prohibiting guessed or reused phone numbers.

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 state readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds behavior beyond that: the result content differs by mode, and the no-argument mode implicitly requires the user to have connected a Foundaree account. It does not mention pagination, limits, or what a missing/invalid id returns.

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?

Opens with the scoping statement ('One place to follow up') then walks the three input cases in order, matching the agent's decision flow. Three sentences, no filler; the only mild cost is the long trailing clause in the last mode.

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 returns, and it does so per mode. What's missing is disambiguation from the similarly named siblings and any note on precedence when both ids are passed, which matters for a two-optional-parameter 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 coverage is 100%, so the baseline is 3, but the description genuinely adds meaning the schema lacks: it explains what each id selects and, critically, that omitting both is a valid mode with its own result set (required parameters = 0). It does not clarify precedence if both ids are supplied.

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 defines a specific follow-up tool and enumerates exactly what is returned in each of three input modes (bookingId, errandId, neither), which is far more informative than the vague name 'check'. It never contrasts itself with close-looking siblings like check_errand, my_bookings, or my_connection_requests, so it stops short of full 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 spelled out conditionally: pass bookingId when following up on a book call, pass errandId when following up on find_and_ask, and omit both for an account overview. That gives clear context for every input combination, but there are no exclusions or pointers to the overlapping siblings an agent would otherwise have to disambiguate manually.

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, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavior beyond that: accepted people will call the user, and Foundaree does not arrange the time. This helps the agent set user expectations. No contradictions with 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 description is three sentences, front-loaded with the core purpose, then the usage trigger, then a key behavioral caveat. Every sentence earns its place, 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 read-only tool with one parameter and no output schema, the description covers everything an agent needs: what the tool reports (accepted/declined/not answered), when to invoke it, and the real-world action after acceptance. The schema and annotations handle the rest, making the definition complete.

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

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

Schema coverage for errandId is 100%, so the description does not need to restate the parameter type or constraints. It does reinforce that the errandId comes from find_and_ask, which matches the schema description. This adds minimal extra meaning, so the baseline of 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?

The description states a specific verb ('Check') and resource ('an errand started with find_and_ask'), then details the exact outcome ('which of the people asked have accepted, declined or not answered yet'). It clearly distinguishes this tool from siblings, especially find_and_ask which creates the errand, and the title reinforces the purpose.

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 an explicit trigger ('Use it when the user asks "did anyone get back to me?"') and ties the tool to errands created by find_and_ask. It implies this is the status-check companion to find_and_ask, making the when-to-use unambiguous.

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 say the tool is non-read-only, non-idempotent, and non-destructive. The description goes far beyond that by disclosing that nothing is published, a private draft is saved, a one-time 7-day finishUrl is returned, and nobody is emailed or texted. This is rich behavioral context that annotations alone would not provide.

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?

Every sentence adds a distinct fact: purpose, usage scope, data-filling rule, publication behavior, link lifetime, and notification side effect. It is slightly long but tightly packed and front-loaded with the primary action.

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 with an output schema, the description covers when to call, what to fill, side effects, and the required post-call action ('Show the user the link'). It also explains the draft's privacy and one-time-use behavior, leaving no significant gap for an agent to invoke it 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 description coverage is 100%, so the baseline is 3. The description adds a cross-parameter rule: fill only details the user gave about themselves and never guess, plus 'Only name is required.' This is meaningful guidance across all 15 parameters and helps prevent hallucinated values.

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: 'Start a Foundaree profile for the user.' It clearly distinguishes from sibling read/search tools like get_person, search_people, and match_people by focusing on creation/joining rather than retrieval.

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?

Explicitly scopes when to use: 'Use it only when the user asks to join Foundaree, to be listed on it, or to create their own profile.' It also instructs to never fill details about someone else, effectively excluding look-up scenarios.

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 readOnly/idempotent/non-destructive, so the description focuses on what annotations cannot express: the return shape (people, businesses, jobs lists with `kind` and `url`, businesses with `price` and `bookable`, plus a `next` hint) and the caveat that Foundaree is new and empty lists should be reported honestly. That is substantive disclosure, though it says nothing about result quality, ranking, or latency.

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 paragraph: purpose first, then usage rules, then return shape, then next steps. The long category enumeration (plumber, electrician, tutor... bakery, salons, tiffin) is verbose but earns its place by helping an agent map colloquial needs to this tool rather than a narrower sibling.

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 supplies the return contract itself (three lists, item fields, `next` hint), plus empty-result guidance and pointers to get/book. For a 5-parameter, single-required search tool this is everything an agent needs to call it and interpret the response 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 the baseline is 3. The description adds useful example phrasing for `need`/`place`/`area` ('"plumber free tomorrow" in "Kochi", area "Kakkanad"') and explains the `kind` default, but it describes the default as searching 'all three' while the schema's `any` enum also includes `apps`, which the description never mentions — a small mismatch that leaves one enum value unexplained.

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 (search) and resource (everything on Foundaree), then enumerates the concrete domains covered — people, delivery, farm products, professionals, businesses, jobs. This clearly separates it from narrower siblings like search_people, search_organizations, and search_opportunities, which an agent can rule out without opening schemas.

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 explicit routing rules: 'Set `kind` only when the user clearly wants one of people, businesses or jobs; the default searches all three', plus 'Use get for the full details of one result, and book to book or order.' It even covers the empty-result case ('say so rather than guessing'), so when-to-use, when-not-to-use, and next-step alternatives are all 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?

Beyond the annotations, the description discloses key behavioral traits: real people will be contacted, their call-back is the only confirmation mechanism, nothing is confirmed until they call, and no account is needed. It also warns that consent is required before acting, which is critical for an external-contact side effect. This does not contradict the 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 description is longer than a terse tool doc, but every sentence earns its place: the example, ranking behavior, alternative tool routing, consent warning, confirmation semantics, and next step all add operational value. It is front-loaded with the core action and ends with practical return handling.

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 tool with 9 parameters, no output schema, and real-world side effects, the description is complete enough. It explains the return artifact (errandId), the follow-up tool (check_errand), the confirmation model, and the consent requirement. There is no output schema, so the description appropriately carries the return-value explanation.

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 the baseline is 3. The description adds value by emphasizing that name and phone must be the user's own details and by connecting the 'best one to three' behavior to the howMany parameter and the ranking behavior. This goes slightly beyond the schema without repeating 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 is specific and action-oriented: Foundaree searches, ranks, sends booking requests, and reports who was asked. It also clearly differentiates from siblings by saying 'Use this instead of search_people + request_appointment' when the user wants a sorted outcome rather than a list.

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 an explicit decision rule: use this instead of search_people + request_appointment when the user wants the whole errand handled and sorted. It also states prerequisites (user's own name/phone, clear consent) and directs the agent to check_errand later, so when-to-use and follow-up are both covered.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's value-add is the privacy caveat: phone/WhatsApp are returned only 'when they chose to show them', warning the agent that contact fields may legitimately be absent rather than an error. It adds no further context on cost, rate limits, or what a missing/invalid username produces.

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

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

Front-loaded with the core statement, then justification for the parenthetical field lists, then the call instruction last. The three parallel field enumerations are long but earn their place, since there is no output schema to convey return shape; only the mini_app kind goes unaddressed.

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, listing the returned fields per kind is exactly the right compensation, and the conditional-privacy note is essential context. The miss is that 'mini_app' is a valid kind in the required enum but has no described return shape, so an agent handling that case gets no guidance.

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 would be 3, but the description adds provenance that the schema does not: both values must be copied verbatim from a prior find result, which prevents the agent from fabricating a username. Minor gap: the enum's fourth value, mini_app, is never mentioned (the schema's username description covers the slug case only).

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 — 'Full details of one result from find' — and immediately enumerates what 'full' means for each of the three primary result kinds (skills, services with prices, hours, badges; bookingsEnabled; role/type/place). This distinguishes it from the sibling 'find' (search/list) and from 'get_person' (single kind) without the agent needing to open a 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?

'from find' and 'Pass the kind and username that find returned' clearly establish the prerequisite workflow: this tool is invoked on a result produced by find. It does not, however, explicitly exclude or contrast itself with the overlapping sibling 'get_person', leaving the agent to infer which to prefer for a person result.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description does add real behavioral context: conditional field population (`licence` only once verified, contact fields only when made public), the two response views (text JSON vs structured profile-card list) and MCP Apps rendering. However it spends most of its length on data-shape exposition rather than call behavior, and never states what an error or a missing username path looks like.

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 paragraph that crams in exhaustive output-field documentation (services, licence, workProof, GitHub facts, updatedAt) via nested backticked terms. The purpose is front-loaded, but an output schema exists, so most of this volume restates structured data and buries the one operationally important line (the two response views) mid-paragraph.

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?

Given a single-param, read-only lookup with an output schema and full annotation coverage, the definition leaves nothing critical unanswered about what the call does or returns. The only gap is the absence of a not-found/error description beyond the `found` flag, which is minor here.

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% with a single required `username` carrying its own example, so the schema does the work. The description only restates "for a username" and adds nothing about format, casing or normalization (e.g. whether "Maya-Chen" resolves to "maya-chen"). 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?

Opens with a specific verb+resource ("Retrieve the full public profile for a username") and enumerates what the profile contains, so the agent knows exactly what it gets back. It stops short of naming how it differs from siblings like search_people, find or match_people, which also surface people.

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?

No statement of when to use this versus search_people, find, match_people or get. The requirement for an exact username is only implicit in the schema. An agent must infer that this is the full-profile-by-handle path while search_people is the discovery path.

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 cover safety (readOnly, idempotent, non-destructive), yet the description adds substantial behavior beyond them: the scoring formula (matched/required, with 1 vs ½ weighting), tie-break order, the score-0 fallback flag, the dual text/structured response views, and the meaning of foundareeRole.

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 and usage before mechanism, and every sentence carries information. It is dense and long, with some detail (e.g. Foundaree's first 150 members) that is more trivia than decision-relevant, but nothing is truly 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?

Despite 9 parameters and no required fields, the description covers filtering vs scoring, tie-breaking, fallback, and return shape/views, so an agent can call and interpret it correctly. The output schema is even restated helpfully rather than left unexplained.

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%, but the description adds semantics the schema does not: which params act as hard filters (location, area, workType, category, availability, lookingFor) versus which only score (skills), and how q both derives skills and narrows by full text.

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 ('Rank public Foundaree profiles against a list of required skills') and immediately contrasts with 'searching for a known person', which cleanly separates it from siblings like search_people and get_person.

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 explicit when-to-use triggers with concrete example queries and an explicit when-not ('rather than searching for a known person'), plus the skills-vs-q decision rule. Routing is unambiguous.

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 readOnly, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: results are sorted with waiting ones first, the user must have connected their Foundaree account, and the status is framed as waiting for an answer. This goes beyond annotations, though it could mention edge cases like an empty account.

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 short, purposeful sentences. The first defines the output content, the second gives usage triggers, the third states the prerequisite, and the fourth suggests a next action. No filler or repetition of schema/annotation data.

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?

Despite lacking an output schema, the description explains the returned content (who, what, when, status) and behavior (pending first). For a no-parameter read-only tool with strong annotations, everything needed to select and invoke it correctly is present.

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 are zero parameters and the schema is empty, so the baseline is 4. The description clarifies that the tool implicitly operates on the signed-in user's identity, which adds meaning beyond the empty schema even though no parameters need explanation.

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 opens with a specific verb and resource: 'List the booking requests people sent to the signed-in user,' and enumerates exactly what is shown (who asked, what they need, when, pending status). This clearly distinguishes it from siblings like my_connection_requests or request_appointment.

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

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

It gives explicit triggers: 'Use it when the user asks what is waiting on Foundaree, who wants to book them, or what they have not answered yet.' It also names a prerequisite (connected Foundaree account) and routes follow-up to the sibling respond_to_booking, leaving no ambiguity.

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, idempotentHint, and destructiveHint, so safety behavior is covered. The description adds useful scope information about including both received and sent pending requests, but does not disclose response shape, pagination, or any other behavioral details beyond that scoping.

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 with no filler. The core action and object are front-loaded, followed by concrete usage triggers and a pointer to the follow-up tool. Every sentence contributes value.

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 listing operation with strong annotations and a straightforward purpose, the description is complete. It tells the agent what is listed, when to use it, and how to continue the interaction, leaving no critical gap 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?

The tool has zero parameters and the schema coverage is trivially complete, so the description has no parameter semantics to add. The baseline for zero-parameter tools is 4, and the description appropriately relies on the implicit signed-in user context rather than introducing parameters.

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

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

The description uses a specific verb ('List') and clearly identifies the resource: connection requests for the signed-in user, both incoming and outgoing pending ones. It is distinct from sibling tools like respond_to_connection, which handles acting on requests, and my_bookings, which covers a different domain.

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 explicit triggers: 'when the user asks who wants to connect, or what is waiting on Foundaree.' It also points to the relevant sibling, respond_to_connection, as the next action, providing routing guidance beyond a simple listing.

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 show readOnlyHint=false, but the description adds crucial side-effect details: the request appears on Foundaree and via email, the person calls back if available, and nothing is confirmed until the call happens. It also discloses a rate limit ('One open request per phone number and person; a few per number a day'), which is not in the 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 description is moderately long but every sentence carries essential information: purpose, examples, safety, consent, side effects, rate limit. It is well-structured and front-loaded with the action and examples, no filler.

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

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

For a mutating tool with real-world side effects, the description covers the full workflow: lookup prerequisite, user consent, what happens after the request (person sees/calls back), and confirmation semantics. Since an output schema exists, return values are not needed, and the description leaves no critical 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?

The input schema provides 100% parameter descriptions, so the baseline is 3. The description adds useful constraint on 'name' and 'phone' by emphasizing they must be the user's own and never guessed/reused, and it tells how to source 'username' (search_people/match_people), but these are also partially in 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?

The description clearly states the action: 'Send a booking request to one person on Foundaree' and provides concrete examples ('book this plumber', 'ask this dentist'). It distinguishes itself from sibling search tools by instructing to use search_people or match_people first, positioning this as the action after discovery.

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 an explicit trigger condition: 'Use it only when the user asked to book or contact that person' and requires prior lookup ('Find the username with search_people or match_people first'). It also mandates user consent before the call and forbids guessing phone numbers, which is clear when-to-use 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?

Beyond the annotations, the description reveals that the action represents the user's answer to a real person, carries social weight, and must not be performed without explicit user confirmation. It also discloses that acceptance has no scheduling side effect. These are meaningful behavioral warnings not present in 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?

Three dense sentences, each earning its place: what the tool does, where the id comes from, and the critical safety caveat. The procedural front-loading makes the important confirmation requirement immediately visible.

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 mutation tool with no output schema, the description covers the prerequisite, the required user confirmation, and the post-call limitation about scheduling. An agent has enough context to invoke it correctly and to explain the outcome to the user.

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 value by emphasizing that bookingId comes from my_bookings and that 'answer' is the user's decision rather than the agent's judgment, reinforcing the enum with important pragmatic context.

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: 'Answer one booking request sent to the signed-in user.' It also makes the accept/decline role clear and distinguishes itself from siblings by scoping to booking requests and pointing to my_bookings for the id.

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

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

It gives explicit workflow: get the id from my_bookings first, read the request back to the user, and obtain a clear yes before calling. It also states a key limitation—accepting does not arrange a time—so the agent knows not to treat this tool as an appointment scheduler.

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 mark the tool as non-readonly, open-world, non-idempotent, and non-destructive. The description adds a valuable behavioral disclosure: 'Declining removes the request quietly; the other person is not told they were declined.' This goes beyond the annotations and informs the agent of the side effect. It does not contradict any annotation, so it's a solid 4.

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 two tightly packed sentences. The first sentence states the purpose and the second covers prerequisite, user confirmation, and the decline side effect. Every clause earns its place, with no fluff or redundant content.

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 tool with two required parameters, an enum, no output schema, and no nested objects, the description is complete. It covers the prerequisite (get id), the required user confirmation, and the behavioral nuance of declining. Nothing an agent needs to call this correctly is missing. The annotations cover the side-effect profile, and the schema covers the parameters.

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 are well-documented. The description adds semantic value by explicitly tying the requestId to 'my_connection_requests', clarifying its source. It also implies that 'answer' should reflect the user's decision from the confirmation step. Even though the schema fully describes the parameters, this extra source hint elevates the score above 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?

The description opens with a precise verb+resource: 'Answer one connection request sent to the signed-in user.' It clearly distinguishes itself from siblings like my_connection_requests (which lists requests) and respond_to_booking (which handles bookings). The accept/decline action is explicit, leaving no ambiguity about what the tool does.

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 explicit usage guidance: 'Get the id from my_connection_requests first' establishes the prerequisite, and 'Tell the user who it is and what they wrote, and get their yes before calling this' directs the agent to confirm with the user. It also notes that declining removes the request quietly, which sets expectations. No alternatives are named, but the tool is specialized enough that this is sufficient.

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 readOnly, idempotent, and non-destructive, so the description adds value by specifying the includeClosed filtering behavior and the absence of application side effects. The caution about Foundaree being new and potentially having few results is helpful behavioral context 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 description is well-structured and front-loaded: purpose first, then usage, behavior, return format, and side-effect clarification. Every sentence adds unique value, with no filler. It is longer than average but justified given the tool's complexity and the need to convey multiple behaviors.

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?

Complete for a search tool: covers what it searches, how to invoke it, what results look like (items structure and total), the includeClosed option, and the realistic data scarcity. No output schema exists, so describing the return JSON is necessary and done well. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema documents all parameters. The description adds meaning by explaining what query matches (title, description, city, skills) and clarifies includeClosed behavior, which goes beyond the schema's basic property descriptions. This extra context justifies a score above the 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 (search) and resource (public openings on Foundaree) and enumerates the role types it covers. It clearly distinguishes from sibling search tools (search_people, search_organizations) by focusing on openings, so an agent can pick it without ambiguity.

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?

Provides explicit triggers ('when the user is looking for work or a role', 'asks what a company is hiring for') with concrete examples. It also states what it does not do (does not apply for anyone) and warns about sparse data, giving clear guidance on when to use and what to expect.

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 cover read-only, idempotent, and non-destructive behavior, and the description stays consistent. It adds useful context beyond annotations: Foundaree is new, results may be few or none, and the agent should say so rather than guess. This is genuine behavioral guidance that structured fields do not provide.

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 four sentences with no filler: purpose and examples first, usage guidance, return shape, data-sparsity caveat, and related-tool pointer. Every sentence earns its place and the structure supports quick agent comprehension.

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?

Even without an output schema, the description names the return envelope and item fields, so the agent knows what to expect. It covers what to search, how to frame results, and which sibling tool handles open roles, making it complete for a simple two-parameter search 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 coverage is 100%, with meaningful descriptions for both the query and limit parameters, including defaults and bounds. The description reinforces query semantics with examples but adds little beyond what the schema already states, so the baseline of 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 clear action: 'Search public company and organization pages on Foundaree' by name, activity, or city, and gives concrete query examples. It also distinguishes itself from person search ('rather than one person') and from open-roles search by pointing to search_opportunities.

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?

Explicitly tells the agent when to use it: when the user needs a company or team rather than a single person. It also routes company open roles to search_opportunities. It does not explicitly name search_people as the alternative for person lookups, but the contrast is clear enough.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial behavior beyond them: which fields each result carries, the tie-break rules (recency boosting, founding members first), the 100-result pagination ceiling, and the fact that phone numbers and emails are deliberately withheld. This is exactly the kind of context structured fields cannot convey.

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 and filter mechanics are front-loaded and the ordering is logical, but the passage is well over 250 words and includes low-value detail for a caller, such as the MCP Apps card rendering in ChatGPT/Claude and the explanation of foundareeRole membership. Several clauses restate what the input schema already documents at 100% coverage.

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 an 11-parameter, zero-required search tool with an output schema, the description covers everything an agent needs: precondition, filter semantics, ranking and tie-break behavior, result cap, withheld fields, and the follow-up tool for contact data. Nothing material is left to inference.

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 baseline is 3, but the description adds genuine meaning: OR vs AND semantics for category/skills/lookingFor, plain-language definitions of workType, and the note that 'area' also matches the areas a person says they cover (which the schema does not state). The parameter guidance therefore exceeds what an agent would get from the schema alone.

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 ('Search public Foundaree profiles') immediately clarified by the two mechanisms (free-text query and structured filters). It explicitly separates itself from the sibling get_person, which is named as the route for contact details, so an agent can distinguish it without opening either 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?

Gives a hard precondition ('give at least one'), advises narrowing with filters when paging hits the 100-result cap, and directs agents to get_person for phone/email. It does not contrast with other search-family siblings such as match_people or search_opportunities, so the alternative-selection guidance is incomplete but the when-to-use context is clear.

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

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

Annotations already indicate a mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds important behavioral context: the change is public and affects the user's visibility in search, and it explicitly recommends confirmation before calling. This goes beyond the annotations and helps the agent understand the social impact and consent requirement.

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 two concise sentences with no filler. The first sentence states the action and the values, the second explains the impact and provides usage guidance. It is well-structured and front-loads the core purpose.

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 tool with one parameter, no output schema, and annotations covering idempotency and non-destructiveness, the description covers all necessary aspects: the action, the allowed values, the public impact, and the confirmation requirement. Nothing essential is missing for an agent to call it 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?

The input schema has 100% coverage with an enum and a description for the single parameter. The description lists the three enum values in prose, which adds readability but does not provide additional semantic information beyond the schema. Since schema coverage is high, a baseline of 3 is appropriate; the description offers no extra syntax or format details.

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 states the verb (change), the resource (the signed-in user's availability on their Foundaree profile), and the three possible states (available, open_to_offers, not_looking). It also explains the consequence (public, affects search visibility), which distinguishes it from sibling tools that operate on bookings, connections, or people. The purpose is unambiguous and specific.

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 usage context: when the user says they have finished a job, are fully booked, or want to be found again. It also advises confirming with the user before calling, which is a strong operational guideline. It doesn't explicitly state when not to use it or name alternatives, but the context is sufficient to guide selection among siblings.

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 the annotations, it discloses that the reply originates from the partner (openWorldHint is confirmed, not repeated), warns that the response is untrusted data whose embedded instructions must not be followed, and clarifies that payment happens outside Foundaree. It does not warn that repeated calls of a non-idempotent action can duplicate a booking or order, which is the main residual risk.

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

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

Front-loaded with the action, then the discovery path, then the safety constraints; nearly every sentence carries distinct information. The opening sentence is long and parenthetical-heavy, which slows scanning slightly.

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

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

Covers discovery, invocation, consent, and trust handling of the external response, which is strong for an open-world, non-idempotent tool with no output schema. It stops short of describing failure behavior (unknown slug or operation) or the duplicate-action hazard, which an agent would still need to infer.

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 3 is the floor. The description adds real constraint beyond the schema by saying `input` must contain exactly those fields and that `app` is the slug and `operation` the name obtained from `get`, which anchors where each value comes from.

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: calling a single operation of a partner mini app, with the domain examples (cab company, delivery app, shop). It also explicitly positions itself relative to siblings by naming `find` (lists mini apps) and `get` (shows each operation and its fields) as the discovery path.

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 the exact workflow: use `find` to get the slug, `get` to see operations and fields, then call with `app`/`operation`/`input`. It also states a hard precondition for the most dangerous case — kind "action" operations require the user's account to be connected and the user's explicit yes.

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