Create estate guest visit invites and read your Clannit notifications (including past invite codes…
Scored across 11 tools
Several tools are described only as 'Run the X pipeline' (fetch_resource, fetch_external_resource_file, fetch_forum_announcements, fetch_forum_profile_photo, fetch_user_profile_picture, fetch_user_school, list_forum_posts), giving an agent no basis to distinguish them. Pairs like fetch_resource vs fetch_external_resource_file and fetch_forum_profile_photo vs fetch_user_profile_picture have unclear boundaries, while only the invite, notifications, advertisements, and login tools are clearly separable.
Names are predominantly verb_noun snake_case (create_guest_invite, fetch_notifications, fetch_user_school). Minor deviations exist: list_forum_posts uses list_ where the other read tools use fetch_, and login_and_register_push_notifications conjoins two actions, but the overall pattern is predictable.
11 tools is a reasonable size for an estate/community app covering invites, notifications, forum, profile, and auth. However, several are thin one-line pipeline wrappers rather than distinct capabilities, which slightly inflates the surface.
The read side is broad (notifications, forum, ads, profile, school, resources) and invite creation plus login are covered. But there is no way to cancel/update an invite, no forum post creation despite list_forum_posts, no profile update, and no logout, leaving notable lifecycle gaps.
Create a guest visit invite. Visit times are built in Lagos (WAT) by a CLI step — do not pass step_18_body_from_* hour fields. Collect guest first AND last name before preview. Always emit_display preview before Confirm. After success, display_data.invite_code MUST be the exact numeric data.code / guest_invite_code — never redact or hide for privacy.
| Name | Required | Description | Default |
|---|---|---|---|
| visit_end_wat | No | Optional end in WAT. Prefer visit_duration_hours when user gives a duration. | |
| guest_last_name | Yes | Guest last name (required — ask in input form if user only gave one name) | |
| visit_start_wat | No | Optional start in Lagos time (WAT), e.g. 2026-10-06T22:30. Omit for “from now”. | |
| guest_first_name | Yes | Guest first name (required) | |
| notification_message | No | Short user-facing sentence for this action if the follow-up reply fails. Plain text only; do not mention template syntax or variable names. | |
| visit_duration_hours | No | Hours from visit start (default 2). Use for “from now for 2 hours”. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses important behavior: Lagos/WAT time handling, a preview-before-confirm requirement, and post-success handling of the invite code. It stops short of covering permissions, error behavior, or broader side effects, so it is strong but not exhaustive.
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 tool purpose and then lists only operational rules that matter. It is appropriately sized for a workflow-sensitive creation tool, though the internal jargon around step_18_body_from_* is slightly cryptic.
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 no annotations and no output schema, the description does well by specifying the critical invite_code output handling and the preview/confirm workflow. It still does not describe the full return payload, error cases, or permission requirements, leaving some completeness gaps.
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 parameter schema already documents all six fields, including WAT timing and name requirements. The description reinforces required guest names and warns against passing step_18_body_from_* hour fields, but adds limited meaning beyond the already-complete 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 opens with a precise verb and resource: 'Create a guest visit invite.' This is specific enough that an agent can distinguish it from all sibling tools, which are fetch/list/login operations rather than invite creation.
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 provides clear procedural guidance: collect both guest names before preview, always emit_display preview before Confirm, and do not pass step_18_body_from_* hour fields. It does not name alternative tools or explicitly state when not to use this one, but the workflow context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the fetch_external_resource_file pipeline.
| Name | Required | Description | Default |
|---|---|---|---|
| notification_message | No | Short user-facing sentence for this action if the follow-up reply fails. Plain text only; do not mention template syntax or variable names. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, yet it discloses nothing: no side effects, no auth or permission requirements, no rate limits, no return shape. Calling it a "pipeline" adds no actionable information.
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 short sentence with no padding, but brevity here reflects under-specification rather than efficiency. There is no front-loaded statement of what the tool returns or when to call it.
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?
No annotations, no output schema, and a description that gives no information about the fetched resource, its format, or the purpose of the notification_message fallback. An agent has essentially nothing to act on beyond the tool name.
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 single notification_message parameter is fully documented in the schema, establishing the baseline of 3. The description adds nothing about it, and notably does not explain why a fetch operation takes a user-facing failure message.
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?
"Run the fetch_external_resource_file pipeline" restates the tool name as a pipeline invocation without saying what is actually fetched, from where, or what the result represents. It is effectively a tautology, though the name itself hints at fetching an external resource file.
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 when-to-use guidance, no exclusions, and no mention of the many sibling fetch_* tools (fetch_resource, fetch_user_profile_picture, etc.). An agent cannot tell from this text when to pick this tool over fetch_resource.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the fetch_forum_announcements pipeline.
| Name | Required | Description | Default |
|---|---|---|---|
| notification_message | No | Short user-facing sentence for this action if the follow-up reply fails. Plain text only; do not mention template syntax or variable names. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, yet it discloses nothing about read-only vs mutating behavior, side effects, permissions, scope, or results. The interaction between the notification_message parameter and an implied follow-up reply is never explained.
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?
It is a single sentence with no bloat, but it is under-specified rather than concise: the one clause it contains conveys no actionable information. Brevity here costs clarity rather than earning it.
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 annotations and no output schema, the description must explain what the tool does and what an agent should expect; instead it says only 'run the pipeline'. An agent cannot determine scope, results, or failure behavior from this definition.
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 parameter is documented in the schema, including its plain-text constraint. The description adds no meaning beyond the schema, so 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 restates the tool name as 'Run the fetch_forum_announcements pipeline' with no added specificity about what an announcement fetch actually returns or covers. An agent learns nothing it could not infer from the name alone, and no distinction from siblings like list_forum_posts or fetch_notifications is drawn.
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?
There is no guidance on when to use this tool, when not to, or which sibling to prefer for forum content. The word 'pipeline' hints at a multi-step operation but gives no conditions for invoking it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the fetch_forum_profile_photo pipeline.
| Name | Required | Description | Default |
|---|---|---|---|
| notification_message | No | Short user-facing sentence for this action if the follow-up reply fails. Plain text only; do not mention template syntax or variable names. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden, yet it says nothing about permissions, side effects, rate limits, caching, or return value. Calling it a 'pipeline' implies hidden multi-step behavior that is never explained.
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?
It is short, but the brevity stems from under-specification rather than efficiency; the one sentence conveys no actionable information and reads as an internal pipeline label leaked to the agent.
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 annotations, no output schema, and zero behavioral detail, an agent has no basis to decide whether or how to invoke this tool correctly. Everything needed to call it safely is absent.
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 single parameter (notification_message) has full schema description coverage (100%), so its semantics are already documented in structured form. The description adds nothing about parameters, which is the baseline-3 case when the schema does the heavy lifting.
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 restates the tool name almost verbatim ('Run the fetch_forum_profile_photo pipeline') and adds only the vague word 'pipeline'. It gives no indication of what the photo is, where it's fetched from, or how this differs from sibling 'fetch_user_profile_picture'.
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 when-to-use, when-not-to-use, prerequisites, or alternative is mentioned. With siblings like fetch_user_profile_picture and fetch_resource in scope, the absence of any routing guidance is a real gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Marketing/promo advertisement cards for guest invites on the estate (image + open ad link). Do NOT use for invite history, sent invite links, or visitor list — use fetch_notifications instead. GET .../guest-invite/advert (steps 1, 16, 17). Agent-only; hidden from chat suggestion buttons.
| Name | Required | Description | Default |
|---|---|---|---|
| notification_message | No | Short user-facing sentence for this action if the follow-up reply fails. Plain text only; do not mention template syntax or variable names. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the load and does disclose the return content (image + open ad link), the endpoint path, and the agent-only visibility constraint. It does not explicitly state that the call is side-effect free, nor any auth/permission or pagination behavior, which is the remaining gap for an unannotated 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?
Front-loaded with the resource definition, then the exclusion, then operational notes; every clause carries signal. The '(steps 1, 16, 17)' reference is slightly opaque without context but is compact.
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?
No output schema exists, and the description compensates by describing the returned card content, the endpoint, and the usage boundary. Only read-only/auth semantics are left unstated, which is a minor gap for a fetch 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 the single optional notification_message parameter is fully documented in the schema itself. The description adds nothing about it, but does not need to; 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 resource (marketing/promo advertisement cards for guest invites) with the payload shape (image + open ad link) and the exact endpoint. An agent can distinguish it from fetch_notifications and the other fetch_* siblings without inspecting any 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?
Explicit exclusion list ('Do NOT use for invite history, sent invite links, or visitor list') plus a named alternative (fetch_notifications) and an extra audience constraint ('Agent-only; hidden from chat suggestion buttons'). Both when-to-use and when-not-to-use are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Notifications feed for the logged-in resident, including past guest invites created (names, codes, times). Use for: notifications, invite history, guest-invite activity, check my history. Auth probe before create_guest_invite. GET /notification (steps 1, 2, 15).
| Name | Required | Description | Default |
|---|---|---|---|
| notification_message | No | Short user-facing sentence for this action if the follow-up reply fails. Plain text only; do not mention template syntax or variable names. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, but it discloses useful context: this is a GET endpoint, requires a logged-in resident, and can serve as an auth probe before create_guest_invite. It does not describe read-only safety, pagination, failure behavior, or response shape, leaving meaningful gaps for a fetch tool with no annotation coverage.
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 compact and front-loads the resource and scope, then supplies use cases and an operational cue. The trailing reference to 'GET /notification (steps 1, 2, 15)' is terse and somewhat opaque, but it does not waste space or bury the main 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 fetch tool with one optional parameter, no output schema, and no annotations, the description provides enough context to select and invoke it: purpose, scope, usage examples, and an auth-probe ordering note. It could be stronger with a note on pagination or return behavior, but the core is 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?
There is one optional parameter with 100% schema description coverage, so the schema already defines notification_message. The description adds no meaning about this parameter or its role in a fetch operation, which is the baseline expectation when schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource as a notifications feed for the logged-in resident and specifies it includes past guest invites with names, codes, and times. It does not explicitly contrast with similar siblings like fetch_guest_invite_advertisements, but the scope and contents are concrete enough for an agent to understand what it returns.
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 lists explicit use cases—notifications, invite history, guest-invite activity, checking history—and adds a valuable ordering cue: use as an auth probe before create_guest_invite. It does not state when not to use it or name alternative tools for overlapping needs, so it stops short of the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the fetch_resource pipeline.
| Name | Required | Description | Default |
|---|---|---|---|
| notification_message | No | Short user-facing sentence for this action if the follow-up reply fails. Plain text only; do not mention template syntax or variable names. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, yet it discloses nothing about permissions, side effects, idempotency, or what happens when the fetch fails. The only hint of behavior is the unused notification_message parameter, which the description never explains.
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 single sentence is short but entirely empty of value; it is under-specification rather than conciseness. There is no front-loaded description of action, resource, or expected result.
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 fetch tool with no annotations and no output schema, the description should explain what is returned and how errors surface. It provides none of that, leaving the agent unable to distinguish this tool from any sibling or to predict its results.
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 parameter is well documented in the schema itself, so the baseline of 3 applies. The description text adds nothing about the parameter's role or the fact that it is optional and only used on failure.
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 only restates the tool name ("fetch_resource pipeline") and adds no information about what resource is fetched, from where, or in what form. The vague term "pipeline" obscures rather than clarifies, and there is no differentiation from the ten sibling fetch_* 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?
There is no guidance on when to use this tool versus any of the sibling fetch_* tools (e.g., fetch_external_resource_file, fetch_notifications). No prerequisites, exclusions, or alternative paths are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the fetch_user_profile_picture pipeline.
| Name | Required | Description | Default |
|---|---|---|---|
| notification_message | No | Short user-facing sentence for this action if the follow-up reply fails. Plain text only; do not mention template syntax or variable names. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description bears the full burden, yet it discloses nothing: no auth or permission requirements, no rate limits, no failure modes, and no mention of what the 'pipeline' entails. The odd reference to a 'pipeline' actually raises unanswered questions about side effects.
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?
It is one short sentence with no filler, but brevity here comes from under-specification rather than efficiency; there is no front-loaded statement of purpose or outcome.
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 annotations, no output schema, and a description that only echoes the name, an agent cannot know what this tool returns, whether it mutates anything, or how it differs from fetch_forum_profile_photo. The definition is effectively incomplete for any correct invocation decision.
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 there is only one optional parameter, so the baseline is 3. The description adds nothing about notification_message — notably, it doesn't explain when the fallback reply would fail or why this tool needs a user-facing message at all.
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?
"Run the fetch_user_profile_picture pipeline" merely restates the tool name in imperative form and never says what the tool actually retrieves or returns. It gives no basis for distinguishing it from the sibling fetch_forum_profile_photo, which sounds functionally near-identical.
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?
There is no guidance on when to use this tool, when not to, or which sibling (e.g. fetch_forum_profile_photo) to prefer. The agent must guess from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the fetch_user_school pipeline.
| Name | Required | Description | Default |
|---|---|---|---|
| notification_message | No | Short user-facing sentence for this action if the follow-up reply fails. Plain text only; do not mention template syntax or variable names. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure, yet it says nothing about permissions, whether the operation is read-only, what a 'pipeline' triggers, or what the result looks like. The word 'run' even hints at an execution side effect that is left unexplained.
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?
It is a single short sentence, but brevity here reflects under-specification rather than efficient communication — no sentence conveys actionable information.
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 annotations, no output schema, and an ambiguous 'pipeline' framing, the definition leaves an agent unable to determine what the tool does or when to invoke it; virtually every decision-relevant detail 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?
There is only one optional parameter and its schema description is complete and self-explanatory (a fallback user-facing sentence), so the schema already covers it fully. The description adds nothing beyond that, which is the baseline case for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description restates the tool name ('fetch_user_school') and adds only the word 'pipeline', which conveys no concrete verb or resource semantics. It never says what is fetched, from where, or what a 'pipeline' entails, so it cannot be distinguished from the many fetch_* siblings.
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?
There is no guidance on when to call this versus siblings like fetch_resource or fetch_user_profile_picture, and no stated preconditions, side effects, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the list_forum_posts pipeline.
| Name | Required | Description | Default |
|---|---|---|---|
| notification_message | No | Short user-facing sentence for this action if the follow-up reply fails. Plain text only; do not mention template syntax or variable names. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral burden, yet it discloses nothing: not whether this is a read or mutation, what permissions are needed, what is returned, or any side effects. The word "pipeline" hints at internal mechanics without explaining them.
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 single sentence is short but wastes its only words on restating the name; this is under-specification rather than conciseness. There is no front-loaded explanation of outcome or scope.
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 annotations, no output schema, and a description that only echoes the name, an agent lacks the information needed to invoke this correctly or understand its results. Sibling tools make the missing differentiation especially costly.
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 parameter (notification_message) is fully documented in the schema, so the baseline of 3 applies. The description adds no meaning beyond the schema, but it doesn't need to for this one optional parameter.
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?
"Run the list_forum_posts pipeline" restates the tool name without adding a verb/resource explanation of what listing forum posts actually entails. It is functional tautology: an agent learns nothing beyond the name, and no distinction from siblings like fetch_forum_announcements is offered.
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 when-to-use, when-not-to-use, or alternative is mentioned. With closely named siblings (fetch_forum_announcements, fetch_resource) an agent has no signal about which to pick, so guidance is effectively absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clannit auth login (email + password). Returns JWT in step_1_body_data_token. Requires step_1_body_email and step_1_body_password — collect via collect_user_input or emit_display input BEFORE calling this pipeline. Chat/Android sessions do not register push tokens.
| Name | Required | Description | Default |
|---|---|---|---|
| step_1_body_email | Yes | Clannit account email | |
| notification_message | No | Short user-facing sentence for this action if the follow-up reply fails. Plain text only; do not mention template syntax or variable names. | |
| step_1_body_password | Yes | Clannit account password |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose that a JWT is returned in step_1_body_data_token and that chat/Android sessions do not register push tokens. It omits important auth behavior such as credential handling, what push registration does in non-chat/Android sessions, failure behavior, and what notification_message affects.
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 compact sentences that front-load the login action and return token. Dense field-path jargon like step_1_body_data_token slightly reduces readability, but there is little wasted prose.
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?
It covers the essential login prerequisites and token return path, which are important for an auth call with no output schema. However, it leaves gaps around push notification registration behavior and the role of notification_message, making it only adequate for a tool whose name includes registration.
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 schema already documents all three parameters. The description names the required email and password and explains how to collect them, but it does not add meaning for notification_message beyond what the schema provides.
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 action, 'Clannit auth login' with email and password, so it is clearly authentication rather than data fetching like the sibling tools. However, the tool name also promises push notification registration, while the description only says chat/Android sessions do not register push tokens, leaving that part of the scope somewhat blurred.
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 instructs the agent to collect email and password via collect_user_input or emit_display input before calling this pipeline, which is actionable preparation guidance. It adds a session caveat but does not fully define when to use this login over other possible auth flows, though no sibling auth tools are shown.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
create_guest_invitefetch_external_resource_filefetch_forum_announcementsfetch_forum_profile_photofetch_guest_invite_advertisementsfetch_notificationsfetch_resourcefetch_user_profile_picturefetch_user_schoollist_forum_postslogin_and_register_push_notificationsRead contacts, listings, tenancies and tasks; create a person contact, note or reminder.
Buzz in deliveries and guests: apartment access codes, timed or recurring entry, and access history.
Your household's calendar, tasks, messages and apps. Read, update, or build new apps with AI.
Read Street.co.uk properties, applicants, viewings, tenancies, jobs; create enquiries, notes, tasks.
Add one secure layer between your agents and this server.