Foundaree

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 establish readOnly and idempotent behavior, and the description adds meaningful behavior beyond them: contact fields appear only if made public, the JSON envelope has success/found/person fields, and MCP-aware apps render profile cards. It also correctly implies a non-found result via the found field, which is useful to an agent handling lookups.

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

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

Three sentences with no filler: the first states the core operation and scope, the second states the response envelope, and the third adds useful platform-specific rendering context. Every sentence earns its place and the key action 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 single-parameter, read-only, idempotent lookup with a full output schema, this description covers everything needed: the lookup key, the inclusivity of the returned profile, the conditional visibility of contact info, the response structure, and the rendering behavior. No meaningful gap remains.

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

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

The input schema is fully descriptive (100% coverage) with a clear type, length constraints, and an example ('maya-chen'). The description does not add parameter-level detail beyond referring to username, but that is acceptable because the schema already carries the full burden; 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 names a specific verb ('Retrieve'), a well-defined resource (full public profile), and the lookup key (username), and enumerates the returned content categories (skills, experiences, projects, public contact fields). It is clearly distinct from the sibling search/match tools, which imply discovery rather than direct retrieval by username.

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 makes the invocation context explicit: use this when you have a username and want the full public profile. It does not explicitly name search_people or match_people as alternatives, but the 'for a username' qualifier creates a clear boundary against search-oriented siblings. Slight deduction for not giving a when-not-to-use statement.

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 and idempotentHint=true, so the safety profile is covered. The description adds substantial behavioral detail beyond the annotations: the exact scoring formula (score = matched ÷ required, with ½ for category/lookingFor terms), tie-breaking rules (availability then recency), and the fallback behavior when no skill matches (score 0, fallback:true instead of empty list). No contradiction 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 front-loaded with the core purpose, then flows logically through input semantics, scoring, tie-breaking, fallback, output shape, and rendering behavior. Every sentence adds operational value with no repetition or filler. Though lengthy, the density is warranted given the tool's complexity.

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 tool with rich scoring behavior, an output schema, and a fallback mode, the description leaves nothing essential unaddressed. It covers scoring, ordering, fallback, the JSON response structure, and note about MCP Apps rendering. The agent has all information needed to invoke the tool and interpret its results 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%, which sets a baseline of 3, but the description elevates it by adding cross-cutting semantics not present in the schema: it classifies location, area, workType, category, availability, and lookingFor as hard filters while stating that skills only affect scoring. It also explains how `q` derives skill terms and simultaneously narrows candidates by full text, which is more than the per-parameter schema descriptions convey.

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 opening sentence states a specific verb (rank) and resource (public Foundaree profiles) against a list of required skills. It differentiates from the sibling get_person by explicitly contrasting with 'searching for a known person' and identifies the trigger: the user describes a need rather than a known 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?

The description explicitly states when to use the tool ('use when the user describes a need') and gives an exclusion ('rather than searching for a known person'). It also provides operational guidance on how to supply the input, either via `skills` or by describing the need in `q`, and clarifies the different roles of filters versus scoring terms.

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, so the safety profile is covered. The description adds meaningful behavioral context beyond that: the 100-result paging cap, the guarantee that results never include phone/email, the OR/AND semantics of filters, and the note about MCP Apps rendering profile cards. It doesn't fully describe pagination edge cases or sort order, but the added context is substantial.

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 dense but well-organized: it front-loads the core behavior, then systematically covers filters, paging, return shape, and exclusions. Every sentence earns its place, though the MCP Apps rendering note is a minor extra that could be trimmed. It is longer than the ideal but justified by the 10-parameter surface.

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 search tool with 10 parameters, an output schema, and rich annotations, the description covers the essential operational constraints: the at-least-one-filter requirement, the 100-result paging cap, the OR/AND semantics, and the contact-details exclusion. The output schema handles return structure, so the description doesn't need to. Nothing an agent needs to call this 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 description coverage is 100%, so the baseline is 3. The description adds value by explaining the semantics of each filter group (substring vs exact, OR vs AND), which the schema's individual parameter descriptions only partially convey. It also clarifies the workType enum values with plain-language examples (blue-collar vs white-collar), which the schema does not. This pushes it 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 states a specific verb ('Search') and resource ('public Foundaree profiles'), and immediately distinguishes the tool from siblings by noting it searches public profiles and that get_person is the route for contact details. It also enumerates the exact fields matched by free-text, which removes ambiguity about what 'search' means here.

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 explicitly says to give at least one of free-text or structured filters, explains the 100-result paging limit and advises adding filters to narrow the search, and names get_person as the alternative for contact details. It also clarifies that results never include phone/email, which tells the agent when not to use this tool for contact info.

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