Talpy Aya – AI recruiter that interviews on WhatsApp

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

Goes well beyond the annotations: discloses the plan's open-job limit consumption, the required mcp:write API scope, expected latency ('a few seconds'), and the background profileStatus generation lifecycle. Annotations only supply the generic non-idempotent/non-destructive flags, so this 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?

Front-loaded with the core action and default state, then layers on limits, auth scope, and return behavior. Dense but every clause carries operational value; a slightly longer sentence about profileStatus could be trimmed.

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 compensates by describing the return payload (job id, status, dashboard link, profileStatus) and the async generation follow-up. An agent has everything needed to invoke and interpret the result.

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 title, publish, language, seniority and description are already documented with defaults and examples. The description reinforces the publish default and the language effect on the response text, but adds little syntax or meaning beyond 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?

States a specific verb and resource ('Creates a new job opening') and adds a non-obvious side effect (generates the interview profile Aya will use). It is clearly distinguishable from siblings like detalhar_vaga and listar_vagas, which are read-only lookups.

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?

Explains the default behavior (draft, not public) and the publish=true alternative for immediate opening, plus routing guidance to call detalhar_vaga after profileStatus is 'generating'. It lacks explicit when-not-to-use conditions, but the operational 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?

With readOnlyHint=true already supplied by annotations, the description adds useful context beyond annotations by stating that it does NOT return phone, e-mail or résumé. It also discloses the return payload composition (scores per competency, evidence, red flags, highlights, human decision), which is valuable because no output schema exists.

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 compact sentences. It front-loads the core purpose and then immediately adds return details and exclusions, with no wasted words.

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?

Because there is no output schema, the description carries the burden of explaining return values, and it does so by listing the main evaluation components and explicitly noting excluded sensitive fields. For a read-only single-candidate detail tool with full schema parameter coverage, this is complete enough.

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 both parameters are already documented in the schema. The description does not add syntax, constraints, or default behavior beyond what the schema provides, making the baseline of 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 gives a specific verb and resource: 'Full evaluation of one candidate,' and enumerates the returned content (scores, evidence, red flags, highlights, human decision). It is clear on its own, but it does not explicitly differentiate itself from siblings such as entrevistar_candidato or listar_candidatos, so it falls short of the top tier.

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 what the tool returns but offers no guidance on when to use it versus alternatives. It does not mention entrevistar_candidato, listar_candidatos, or any other sibling, nor does it state when this evaluation is appropriate instead of another tool.

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 openWorldHint=false. The description repeats 'Read-only' without adding behavioral context such as permissions, rate limits, or response format. The note about competencies is about output content, not 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?

Two sentences, front-loaded with the core purpose and a trailing safety confirmation. No wasted words; every sentence contributes.

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 usefully indicates what the tool returns (job details, competencies, weights). It omits any mention of how to obtain the jobId, but the schema covers that. Overall complete enough for a simple read 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 both parameters are fully documented in the schema. The description adds no parameter-level meaning beyond what is already in the schema, which is the baseline expectation.

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 ('Shows') and resource ('one job') with detail on what is included (competencies and weights). It clearly distinguishes from listar_vagas by being singular, but does not explicitly name or contrast with any sibling tool in the description text.

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 only states what the tool does; it gives no guidance on when to use it versus alternatives like listar_vagas or detalhar_candidato. The schema's jobId description hints at using listar_vagas first, but that is not in the tool description.

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?

Despite annotations covering the safety profile, the description adds rich behavioral context beyond them: real WhatsApp/e-mail invites are sent, one interview is deducted from the company balance, and an API key with mcp:write scope is required. This is exactly the kind of side-effect disclosure a mutation tool needs.

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 action, followed by a clearly labeled SIDE EFFECTS segment and return values. Every sentence earns its place with 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?

Though no output schema exists, the description lists the returned fields (candidateId, interviewId, invite channel), and it covers side effects, auth scope, and channel behavior. An agent has everything needed 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 coverage is 100%, so a baseline of 3 applies, but the description adds real meaning by tying phone presence to WhatsApp delivery and e-mail to a web-interview link, which is the routing logic the agent must understand. It does not add syntax detail beyond 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 states a specific verb and resource: adds a candidate to a job and invites them to an interview with 'Aya'. It is clearly distinguishable from siblings like criar_vaga or listar_candidatos, which handle job creation and listing rather than candidate invitation.

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 clear usage context ('Only invite people who applied or agreed to be contacted') and explains the channel-selection logic. It does not, however, explicitly name alternatives for cases where the agent should do something else (e.g., creating a job first via criar_vaga), leaving that 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?

'Read-only' merely repeats readOnlyHint=true so earns no credit, but 'Does NOT return phone, e-mail or résumé' is a genuinely useful privacy/scope disclosure the annotations do not carry, as is the 'highest score first' ordering guarantee. No pagination or result-size behavior is described, keeping it off 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, front-loaded sentences: what it lists, safety posture, and what it withholds. Zero filler and the most decision-relevant information comes first.

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 usefully names the returned fields and the exclusions, which is exactly what an agent needs to interpret results. It omits any note on pagination or result limits for a list endpoint, so it is strong but not fully 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 description coverage is 100% with enums fully annotated for stage and language, so the schema already does the heavy lifting. The description adds no syntax or format detail for jobId, minScore or stage filtering beyond what is documented, 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 ('Lists the candidates of a job') and front-loads the payload ('interview score, profile fit and pipeline stage') plus the sort order. It is implicitly distinguishable from listar_vagas and detalhar_candidato, but no sibling is named explicitly, so it falls short of the top mark.

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 scope ('of a job') implies when to use it, and the schema ties jobId back to listar_vagas, but the description itself gives no when-to-use/when-not guidance and never points to detalhar_candidato for single-candidate detail. Usage is inferable, not 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 description's 'Read-only' line is largely redundant. It does add useful output context (status and per-job candidate counts) beyond the annotations, but nothing about scoping, pagination, or the fact that results default to ATIVA jobs only.

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, no filler. The purpose/return value leads, and the workflow hint follows, so 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 listing tool with no output schema, the description covers purpose, output shape, and workflow placement, which is enough to invoke it correctly. It leaves minor gaps around result scoping/defaults and pagination behavior that would otherwise matter.

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 both parameters (status enum with ATIVA/RASCUNHO meanings and default, language) are fully documented in the schema. The description adds no parameter meaning of its own, so the 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 and resource ('Lists the company's job openings') and even names the returned fields (status, candidate count), so the agent knows exactly what the call produces. It does not explicitly contrast itself with siblings like detalhar_vaga, but the list vs. detail distinction is obvious from the verb.

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 concrete use case: 'Use it to find a job id before looking at candidates or inviting someone,' which tells the agent when this tool belongs in a workflow. It omits any when-not guidance or explicit alternative (e.g., use detalhar_vaga for a specific job's full details).

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 openWorldHint=false, and the description reinforces this with a concrete assurance: it never charges or changes the subscription, and payment occurs only in the dashboard. That is genuine added context beyond the annotation flags, though no rate limits or freshness/caching behavior are mentioned.

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 no filler. The content list is front-loaded, and the read-only caveat is placed at the end where it reads as an important qualifier.

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 and only one optional parameter, the description carries the return-value burden and does so by enumerating what the agent will see. An agent has everything needed to call and interpret this tool 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% and the single optional 'language' parameter is fully documented with its enum and default in the schema. The description adds nothing about the parameter, so the 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?

The description names a specific resource (the company's plan) and enumerates exactly what is returned: current plan, cycle usage against limits, available plans with prices, and the subscription link. This is clearly distinguishable from all siblings, which are recruitment/candidate tools.

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 scope implies when to reach for it (questions about plan, usage limits, pricing, subscribing), and the closing sentence draws a clear boundary by stating that changes must happen in the dashboard, not here. It does not explicitly name alternatives, but no sibling overlaps this domain.

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 openWorldHint=false, so 'Read-only' partly restates structured data. However, 'Contains no personal data' is genuine extra context beyond annotations, telling the agent the output is safe to surface or aggregate. It does not disclose the aggregation time window or whether results are cached, which would matter for a metrics 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?

Two compact sentences, front-loaded with the returned metrics and followed by the two safety-relevant facts. Nothing is padded, though the metric list could be slightly tightened.

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 aggregate with no output schema, the description covers what is returned and the privacy/safety posture, which is most of what an agent needs. The main gap is the absence of any timeframe or scoping note for the numbers.

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 only one optional parameter (language) and schema description coverage is 100%, so the schema already explains it fully, including the default-to-account-language behavior. The description adds nothing about the parameter, so the 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?

The description names the specific resource (company-wide recruiting numbers) and enumerates the metrics returned: open jobs, candidates, completed interviews, average score, plan usage. This lets an agent separate it from list/detail siblings like listar_vagas or detalhar_candidato, which return records rather than aggregates. It stops short of an explicit 'use this instead of X' framing, but the aggregate nature is clear.

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 can infer this is a dashboard-style overview call, but there is no statement of when to prefer it over listar_vagas/listar_candidatos or any prerequisite. No exclusions or alternatives are named, leaving routing to inference.

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