Propstack MCP by usefulapi

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

The description contradicts the idempotentHint=false annotation by stating that Propstack matches on email and updates an existing contact instead of creating a duplicate, which makes repeated identical calls effectively idempotent. Although the description usefully discloses the upsert behavior, return value, and consent-flag limitation, the direct conflict with the structured annotation forces a score of 1.

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 'WRITE: create a CRM contact', then covers the key behavioral facts in three compact sentences plus the endpoint. For an 18-parameter tool, it is appropriately sized and every sentence contributes useful 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?

It covers the most important context an agent needs: that this is a write, the email-based upsert behavior, the return value, and a field limitation. It stops short of explaining permission requirements, partial-update behavior for omitted fields, or what happens when email is absent, but annotations cover the safety profile and the schema covers all 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 coverage is 100%, so the baseline is 3, but the description adds important semantic context by identifying email as the matching key rather than merely a 'primary email address'. It also adds a constraint about consent-related fields that are not part of 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 ('create a CRM contact') and immediately clarifies the matching behavior on email, which distinguishes its upsert semantics from a plain create. It also names the boundary condition (existing email is updated) that separates it from other sibling tools like propstack_update_contact.

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 context for use (create a CRM contact, matched by email) and an explicit exclusion ('Consent flags ... cannot be set here'). However, it does not name an alternative tool for the excluded consent flags or for ID-based updates, leaving the agent to infer routing to propstack_update_contact.

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?

The 'WRITE:' prefix and 'Returns the new deal' align with annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=false) rather than contradicting them, and the return statement adds information annotations cannot express. However, it does not disclose the destructive/irreversible nature or auth requirements beyond what the annotations already state.

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 fragments with zero filler: the write marker, the semantic description with prerequisite pointer, and the return behavior. The most decision-relevant facts (write, what it links, where to get the stage id) are 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?

With no output schema, the explicit 'Returns the new deal' fills the return-value gap, and the pipeline prerequisite resolves the one ambiguous required id. Annotations already carry the safety profile, so remaining gaps (side effects, error cases) are minor.

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 every parameter (note, price, broker_id, contact_id, property_id, deal_stage_id) is already documented in the schema. The description only narrates the three required relationships and adds no format or constraint detail, 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?

States a precise verb ('create') plus the exact resource and its relationships: a deal linking a contact to a property in a pipeline stage. It also names the sibling tool that supplies stage ids, so an agent can distinguish it from propstack_update_deal and propstack_list_deal_pipelines without opening 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?

Gives a concrete prerequisite — fetch stage ids via propstack_list_deal_pipelines — which is clear usage context. It does not state when NOT to use this (e.g., to modify an existing deal, use propstack_update_deal), so it stops short of full when/when-not 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 (write, destructive, non-idempotent, open-world), the description adds real behavioral detail: no e-mail/SMS reaches the contact, the only mail is the assignee reminder when remind_at is set, the new task id is returned, and the endpoint is POST /tasks. These side-effect disclosures are exactly what an agent needs for a mutation 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 'WRITE:' as a mode flag, then purpose, then parameter guidance, then side effects and return value. Dense but every sentence carries independent information 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?

Despite 13 parameters and no output schema, the description covers the three kinds, the linking targets, the side-effect mail behavior, and the return value ('the new task id'). Nothing an agent needs to invoke 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 baseline is 3 and the schema already documents each field. The description still adds value by explaining that note_type_id is the activity type id and cross-referencing propstack_get_reference_data activity_types, plus the requirement that it match the chosen kind.

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 ('WRITE: create a note, a to-do ... or an appointment in Propstack') and enumerates the three variants an agent must distinguish. This clearly separates it from propstack_update_task and the read/get siblings without needing schema inspection.

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 states when each variant applies (note = plain, to-do = due date, appointment = start/end), which is genuine usage context, and clarifies that no external message goes to the contact. It stops short of an explicit 'use this vs propstack_update_task' routing statement, so it is clear context rather than full when/when-not 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?

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint), but the description adds meaningful non-obvious behavior: an explicit list of never-returned sensitive fields (birth data, identity/tax numbers, income, portal token). That is real disclosure the agent cannot get from annotations or schema.

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 dense sentences with the returned-field inventory, sensitivity exclusions, and endpoint all front-loaded; nothing is padded. The field laundry list is long but each item carries selection value for the caller.

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 does the work of sketching the response shape and, importantly, the exclusions, which is exactly what an agent needs to reason about the result. It omits error/not-found behavior and auth requirements, but is otherwise adequate for a simple single-record fetch.

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 all three parameters are already documented in the schema, including the include and custom_fields enums. The description adds nothing about parameter syntax or format, 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 ('One contact by id') plus the exact endpoint (GET /contacts/{id}), which cleanly separates it from propstack_list_contacts. The enumeration of returned fields makes the scope unmistakable.

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?

Retrieval-by-id is self-evident, but there is no explicit guidance on when to use this versus propstack_list_contacts (e.g., for searching by name) or propstack_update_contact. Usage is implied by the id-based framing rather than 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that: it names the underlying endpoint (GET /units/{id}), discloses that text fields are 'clipped' (truncated) and explicitly excludes images and owner data, which tells the agent not to expect those fields.

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 front-loaded sentence plus the endpoint, no filler. The most decision-relevant information (single object, keyed by id, what comes back, what is missing) is packed into the first clause.

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 by enumerating fields and naming exclusions, plus the truncation caveat. Only minor gaps remain, such as behavior on an unknown or unauthorized id.

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% for the single required property_id, so the schema already documents format and bounds (integer > 0). The description only restates 'by id' without adding syntax, error or resolution behavior, 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 ('One property (Objekt) by id') and enumerates the returned facets (address, type, rooms, areas, prices, status, texts). The word 'One' plus the id keying distinguishes it clearly from the sibling propstack_list_properties without 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?

Usage is only implied: an agent can infer this is the single-object lookup keyed by id versus the list endpoint, but the description never states when to prefer it over propstack_list_properties or what to do when the id is unknown. No prerequisites or exclusions are given.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the backing endpoint paths, which hints that contact_tags and property_tags are served by a shared /groups resource, but says nothing about auth, caching or rate limits, so it adds only modest behavior context.

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, no filler, and the purpose is front-loaded ahead of the enum glosses and endpoints. Every clause carries information the agent needs.

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-enum lookup tool there is little to explain, and the kind-to-endpoint mapping is complete. However, with no output schema the description never indicates the return shape (e.g. id/name pairs) an agent must parse to actually reuse the ids elsewhere.

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% and the enum is self-documenting, so the baseline is 3. The description goes beyond that by glossing domain terms — activity_types as note/task/appointment types, reservation_reasons as rejection reasons — which is real semantic value for picking the right enum value.

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 ('Look up the ids used by other tools') and enumerates the exact reference lists returned. An agent can immediately separate this lookup tool from the CRUD/list siblings such as propstack_list_contacts or propstack_list_deal_pipelines.

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 tells the agent why to call it — to resolve ids consumed by other tools — and gives a concrete example ('activity_types ... needed as note_type_id'). There is no explicit when-not guidance or named alternative for tag lookups, so it falls short of 5.

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 (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description's value-add is the disclosure of return shape and the notable detail that body text is 'clipped'. It adds real context beyond annotations, though it does not mention permissions, rate limits, or error behavior for missing ids.

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, densely packed sentence with the identity of the resource front-loaded and the field list in a parenthetical. Nothing is wasted, though the trailing 'GET /tasks/{id}' restates the operation rather than adding 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?

No output schema exists, so the description usefully summarizes the returned fields, and annotations carry the safety profile. For a one-parameter read tool this is close to complete, with only edge-case behavior (not found, incomplete data) left unaddressed.

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% and the single task_id parameter is documented at the schema level as a positive integer task id. The description adds no format or constraint detail beyond the schema, 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 ('One task by id') and enumerates what the returned task contains, including the clarification that a task may be a note, to-do or appointment. It clearly separates single-fetch from list-style siblings, though it does not name an alternative tool explicitly.

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 'by id' framing implies the usage context (retrieve one known task), but there is no explicit statement of when to use this versus list_activities, list_events or a search. Usage is inferable rather than 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and the description adds real behavioral value on top: 'Message and note bodies are not returned' tells the agent what data is deliberately absent from results, and 'GET /activities' names the underlying operation. Return shape and pagination semantics are left to the schema.

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, both front-loaded with the highest-value information: what the timeline contains and what is withheld. Nothing is redundant or padded, and the result-content caveat is placed where it will be read.

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 14-parameter read-only list tool with no output schema, the description covers the returned fields, the filtering dimensions, and one important content limitation. It stops short of explaining pagination or result ordering, though the schema's page/per descriptions partially cover that.

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 every one of the 14 parameters carries its own description, so the schema does the heavy lifting. The description's filter list roughly restates those fields (type, contact, property, project, owner, category, date) without adding syntax, defaults, or format guidance beyond 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?

States a specific verb and resource ('List the activity timeline') and enumerates the activity kinds returned, so an agent knows exactly what the endpoint yields. It does not, however, differentiate itself from the closely related propstack_list_events sibling, leaving potential ambiguity about which list to call for calendar-type items.

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 filter sentence ('Filter by type, contact, property, project, owner, category or date') implies how to narrow results, but there is no explicit when-to-use versus alternatives and no statement of exclusions or prerequisites. Usage is inferable rather than 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 cover readOnly/openWorld/destructive, and the description adds valuable PII transparency by listing what fields are returned and explicitly excluding sensitive data (birth data, identity/tax numbers, income, portal tokens). It also notes archived exclusion default, which is real 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?

Well-structured with the core purpose first, then field disclosure, then search modes. Slightly dense but every sentence carries information. The preamble 'never birth data...' is longer than strictly needed but justified by compliance sensitivity.

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 17 optional parameters, no output schema, and annotations covering safety, the description adequately explains search/filter behavior, PII scope, and archived defaults. It is complete enough for an agent to invoke correctly without opening the schema.

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 goes further by explaining search semantics (free text searches name, email, address, phone; exact matching variants) and the archived parameter behavior, adding meaning beyond the schema's terse parameter descriptions.

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 ('List or search CRM contacts') and immediately distinguishes itself from siblings like propstack_get_contact (single fetch) and propstack_create_contact (mutation). The endpoint reference 'GET /contacts' anchors it further.

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 details the available search and filter modes (free text, exact email, exact phone, status/source/tag/owner/date filters) which implies when to use this tool for discovery. However, it does not explicitly route to alternatives like propstack_get_contact for single lookups.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the GET endpoint and lists returned stage fields, but does not disclose permissions, rate limits, pagination, or error behavior beyond those 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 short sentences are front-loaded with the core purpose and usage. The parenthetical field list is useful given the absent output schema, and the GET path is a compact endpoint reference with no 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?

For a no-parameter, read-only list tool with annotations covering safety, the description is largely complete. It identifies the returned entities and some fields, though without an output schema it could say more about pagination or the full response shape.

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 takes zero parameters, so the baseline is 4. The description appropriately adds no parameter meaning because there is nothing to describe.

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: 'List the deal pipelines with their stages.' It also names the returned fields, which distinguishes it from sibling list tools such as propstack_list_deals. An agent can identify this as the pipeline-configuration lookup without opening the 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?

The sentence 'Use the stage ids to filter deals or to move a deal' gives clear downstream context for invoking the tool. It does not name a specific alternative or state when not to use it, so it falls short of explicit when/when-not routing 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /client_properties) and the domain relationship between deals, contacts, properties and pipeline stages, but says nothing about pagination behavior, result caps or return shape. Useful addition over annotations, but not rich.

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 sentences, front-loaded with the action and the domain model, followed by filters and the cross-reference. No filler or repetition; the endpoint note is terse.

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 read-only list tool with no output schema, the description supplies the domain model, the filter axes and the stage-id cross-reference, while the schema covers pagination details. The only gap is return/pagination behavior, which is partially handled by the per/page schema descriptions (including the next_page hint).

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% (all 15 params carry descriptions, including per/page defaults, ISO date bounds, embed flags), so the schema does the heavy lifting and a baseline 3 applies. The description only restates the filterable dimensions as prose and adds no syntax or semantics beyond what the schema already says.

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 ('List deals') and goes further by defining the domain object ('a deal links a contact to a property and sits in a pipeline stage'), which is the key mental model needed to reason about the sibling list/create/update tools. It also names the sibling propstack_list_deal_pipelines for stage ids, so an agent can route correctly without opening another 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?

It gives concrete filtering guidance ('Filter by pipeline, stage, category..., contact, property, project or owner') and an explicit alternative for one sub-task ('Use propstack_list_deal_pipelines for stage ids'). It stops short of saying when not to use this tool (e.g. single-deal lookup vs get/list) but the 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?

The annotations already declare read-only, non-destructive, open-world behavior, so the description does not need to repeat the safety profile. It adds useful context beyond the annotations: the result set is paged with a next_page token, the returned fields include id+name for linked entities, and the underlying call is GET /events. It still omits auth/permission requirements, but that is a modest gap given the 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?

Three sentences with no waste: the primary purpose and return fields come first, then the pagination instruction, then the HTTP verb/path. Every sentence earns its place and 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?

With no output schema, the description usefully summarizes the returned fields and clarifies that linked entities are id-and-name only, which an agent needs to interpret results. It also covers the pagination contract. Minor omissions (e.g., no mention of default page size or empty-result behavior) keep it from a 5.

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 each of the nine parameters is already fully documented in the schema, and the description only implicitly references the time-window filters (starts_after/starts_before) without adding syntax or edge-case detail. Baseline 3 is appropriate when the schema carries the parameter burden.

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 ("List") and a concrete resource ("calendar appointments (Termine, e.g. viewings)"), and even enumerates the returned fields (title, place, start/end, state, linked contact/property/project). It does not explicitly differentiate itself from the closely named sibling propstack_list_activities, so it stops short of a 5.

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 states the tool operates "in a time window" and gives pagination guidance ("follow next_page"), which implies when it is used. However, it never names an alternative or exclusion condition (e.g., how it differs from propstack_list_activities or when to prefer a single-event lookup), leaving the user to infer routing.

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 destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: 'Not paged; at most 200 are returned', which tells the agent there is no pagination cursor to chase and results are capped, plus the underlying endpoint GET /projects.

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 sentence: identity and domain definition first, then returned fields, then pagination cap, then endpoint. Every clause carries information and there is 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?

With no output schema, the description compensates by listing the returned fields (title, project id, status, address, owner) and the result cap, and the annotations cover the safety profile. Nothing an agent needs to invoke this no-arg read 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?

The schema has zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly does not fabricate parameter talk for a no-arg tool.

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 ('List projects') and immediately defines the domain term ('Projekte: a project groups several property units'), which cleanly separates it from the sibling propstack_list_properties. It also enumerates the returned fields, so an agent knows exactly what this call yields.

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 implied by the name and definition — call it to enumerate projects — but there is no explicit when-to-use guidance, no statement about when not to use it, and no pointer to alternatives such as propstack_list_properties. Adequate but with a clear gap.

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, openWorldHint and destructiveHint, so the safety profile is covered. The description adds genuine extra context by stating that images and owners are NOT returned, which warns the agent it must fall back to another tool for those fields. Pagination behavior is left to the schema's next_page note rather than described here.

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 plus the endpoint reference, with the statement of what the tool is and what it returns front-loaded. There is little waste, though the filter-category list partly duplicates the schema and 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?

For a 20-parameter, no-output-schema search tool, the description does reasonable work: it identifies the resource, summarizes the filter set, and clarifies what is and isn't returned. It omits return shape details (pagination, ordering defaults), but the schema covers pagination and the field list partially compensates for the missing output schema.

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 every one of the 20 parameters is already documented in the schema, making 3 the baseline. The description only restates filter categories at a high level and adds no syntax, format, or interaction detail beyond what the structured 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?

The description gives a specific verb and resource ('List or search properties (Objekte / units)') and enumerates the fields returned (address, type, marketing type, rooms, areas, prices, status). It even names the underlying endpoint (GET /units). It stops short of contrasting itself with siblings like the single-property get_property, so differentiation is implicit rather than explicit.

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 enumerates the available filter axes (free text, status, tag, project, marketing type, object type, price and area ranges), which implies when the tool is appropriate, but it never states when not to use it or which sibling to prefer for a specific lookup. Usage is inferable rather than guided.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value beyond that by disclosing the returned field set and the fact that ids serve as owner/broker filters elsewhere. It omits pagination, ordering, or result-size behavior, which keeps it below 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?

Two tight sentences with no filler: the resource and its fields come first, the usage hint second, the endpoint last as a compact technical anchor. Every clause carries 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 output schema, the description compensates by enumerating returned fields, which is the main thing an agent needs. It does not cover pagination, ordering, or volume limits for an open-world list endpoint, a minor remaining gap for a zero-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?

The tool takes zero parameters, so the baseline is 4 per the rubric. The description correctly indicates no input is needed and instead explains how the output ids are used downstream, which is the relevant semantic here.

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 ('List the users ... of the Propstack account') and enumerates the returned fields (id, name, work email, position, phone, team), plus the German alias 'Nutzer' and the underlying endpoint GET /brokers. No sibling tool lists users, so the scope is unambiguous.

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 concrete downstream guidance: 'Use the ids as owner/broker filters', telling the agent why it would call this and how to consume the result. It stops short of naming alternative tools or stating when not to use it, so it is clear context without exclusions.

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 destructiveHint=true and idempotentHint=true, but the description adds real behavioral value: omitted fields are left untouched (merge semantics) and the response is the updated contact's business fields. It omits auth/permission requirements, and the stated HTTP verb 'PUT' conflicts semantically with the partial-update behavior it describes, but that is an internal wording issue rather than a contradiction of 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?

Three short clauses lead with the 'WRITE:' classification, then the partial-update rule, then the return value and route. No filler, no restatement of the title, and every element earns its place.

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 19-parameter mutation tool the description covers the essentials: write nature, merge semantics, and the return shape, and the annotations cover the safety profile. It does not address failure modes (e.g. unknown contact id, invalid reference ids for client_source_id/client_status_id), so it is slightly short of 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% across all 19 parameters including the nested custom_fields object, so the schema already carries full parameter meaning. The description adds only the blanket rule that unlisted fields are unchanged, which is a semantic nuance (notably for custom_fields) but no field-level 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?

States a specific verb+resource ('change the given fields of an existing contact') and immediately scopes the operation as a partial update on an existing entity, which cleanly separates it from propstack_create_contact and propstack_get_contact. An agent can identify the target record type from the description alone.

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 phrasing 'change the given fields of an existing contact' implies when to use it (existing contact, partial change) but never explicitly contrasts with siblings such as propstack_create_contact or propstack_get_contact, nor states prerequisites like needing a valid contact id. Usage is inferable but not spelled out.

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=false, destructiveHint=true, and idempotentHint=true, so safety is covered. The description still adds real behavioral value by clarifying partial-update semantics ('Fields not given stay as they are') and naming the underlying PUT endpoint, which is not obtainable from the structured fields.

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, front-loaded with the operation class and the partial-update rule before the endpoint. Every clause earns its place with zero padding.

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 update tool whose safety profile is fully carried by annotations and whose parameters are fully described in the schema, the description supplies the key missing behavioral fact (partial update, unspecified fields preserved). It omits any auth/permission notes, keeping it just short of a 5.

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 each parameter (note, price, deal_id, broker_id, deal_stage_id) is already documented in the schema. The description only correlates a couple of params with typical intents ('note or price', 'pipeline stage') and does not add syntax or constraint detail, 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+resource ('change the given fields of a deal') and names the two typical mutations (move stage, update note/price). An agent can distinguish this from propstack_create_deal or propstack_get_contact from the text alone, and the 'WRITE:' prefix signals the operation class immediately.

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 concrete usage context (typical move-to-stage or note/price updates) that tells the agent when this tool is the right choice. It does not explicitly name alternatives (e.g., create_deal) or when-not-to-use, so it falls short of the top tier but is well above implied usage.

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?

The 'WRITE:' prefix and 'PUT /tasks/{id}' disclose the mutation nature and endpoint, and the partial-update behavior is stated. Annotations already flag destructiveHint, so the description needn't repeat safety; it adds useful context about which fields are left untouched.

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-loads the 'WRITE:' intent and operation, packs examples and partial-update semantics into two sentences, ends with the endpoint. Efficient with minimal waste.

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 the operation, scope, partial-update behavior, examples, and endpoint. Without an output schema, it omits return details, but for an update tool with full annotation coverage this is largely 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 is 100%, so the baseline is 3, but the description adds meaning by grouping fields by task type (to-do vs appointment vs note) and giving examples like marking done or rescheduling, which contextually enriches otherwise sparse schema descriptions.

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 (change/update) and resource (note, to-do, appointment), and gives concrete examples (mark done, move due date, reschedule). Easily distinguished from siblings like propstack_create_task and propstack_get_task.

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?

Implies usage for modifying existing tasks, and 'Fields not given stay as they are' clarifies partial-update semantics, but never explicitly says when to use this vs. create_task or update_contact.

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