Trellistate

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

Annotations already provide readOnlyHint=true, so the description correctly reinforces a read-only intent. It adds no additional behavioral traits beyond what annotations imply, which is acceptable given the annotations' presence.

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?

Single sentence, front-loaded with action and resource, no wasted words.

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

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

Given low complexity (one parameter, no output schema), the description sufficiently explains what the tool does and what input is needed. Though it could mention that it requires no additional permissions, the readOnlyHint covers the safety aspect.

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 covers the 'id' parameter with description 'Public listing ID or slug' (100% coverage). The tool description adds an example format ('e.g. lst_abc123...'), providing useful context beyond the schema.

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

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

The description clearly states 'Return the full structured details of a single listing', specifying the verb and resource. It also indicates the input is by 'public ID' or 'slug', distinguishing it from sibling tools like list_recent or search_listings which handle multiple listings.

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 implies when to use: when needing details for a specific listing by ID or slug. It does not explicitly state exclusions or alternatives, but the context of sibling tools provides clear differentiation.

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

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

Annotations already indicate readOnlyHint=true. Description adds that agents are 'active' and on 'Trellistate directory', but lacks details on pagination, rate limits, or ordering. No contradiction with annotations.

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

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

Two sentences, no wasted words. Purpose and use case are front-loaded in the first sentence.

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?

A simple tool with one parameter and no output schema. The description provides basic purpose but omits ordering, active definition, and relationship to sibling 'list_recent'. Adequate but incomplete.

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 0%, and the description does not explain the 'limit' parameter at all. The agent must rely solely on the schema for parameter meaning.

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?

Description clearly states 'List active registered AI agents' with a specific resource and verb. Differentiates implicitly from siblings like 'search_listings' and 'submit_inquiry', but does not explicitly contrast with 'list_recent'.

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?

States 'Useful for agent-to-agent discovery' as a use case, but provides no when-not-to-use guidance or direct comparison to sibling tools like 'search_listings' or 'list_recent'.

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 declare readOnlyHint=true. The description adds that only 'active' listings are returned and they are 'most recently updated', which goes beyond schema. No contradiction.

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 concise sentences, front-loaded with the core action and a usage hint. No unnecessary words.

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

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

For a simple list tool with two parameters and no output schema, the description covers purpose, usage scenario, and parameter relevance. Sibling tools are distinct, so context is complete enough.

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

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

The description links the limit parameter to the 'N' in 'N most recently updated', adding semantic context. The since parameter already has a description in the schema. With 50% schema coverage, description provides modest additional 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?

The description clearly states it returns the N most recently updated active listings, and the tool name 'list_recent' aligns. It distinguishes from siblings like get_listing (single listing) and search_listings (search).

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

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

The description explicitly says 'Useful for periodic agent crawls', providing a concrete usage scenario. It does not mention when to avoid or alternatives, but the context is clear enough.

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

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

Annotations already provide readOnlyHint=true, so the description's focus on searching active listings and default behavior adds useful context without contradiction. It does not disclose any additional behavioral traits beyond what annotations imply, but it is consistent.

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 extremely concise with two sentences, front-loading the core purpose and default behavior. Every word is necessary; no fluff.

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 13 optional parameters, no output schema, and a search tool that likely returns complex results, the description is too brief. It does not mention return format, pagination, sorting, or any advanced filtering behavior (e.g., how multiple filters combine). Significant context is missing.

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

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

Schema description coverage is 54% (7 of 13 parameters have descriptions). The tool description does not add any parameter details beyond what is in the schema, so it relies on the schema's existing descriptions. Baseline of 3 is appropriate as the description offers no extra parameter guidance.

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

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

The description clearly states it searches active Trellistate property listings, and specifies default behavior with no filters. However, it does not differentiate from sibling tools like list_recent (which likely also returns recent listings) or get_listing (single listing).

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 notes that all filters are optional and that no filters returns the most recent listings, implying a default use case. But it does not explicitly state when to use this tool versus alternatives (e.g., list_recent for a simple list, get_listing for detailed view, or submit_inquiry for actions).

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 description correctly indicates a write operation (consistent with readOnlyHint=false) and mentions authentication. However, it does not disclose side effects, confirmation behavior, error scenarios, or rate limits. With no other annotations, this is adequate but lacks depth.

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 concise sentences: the first defines the action and scope, the second adds an essential requirement. No extraneous words, front-loaded with key 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?

The tool has 5 parameters (2 required), a nested object, and no output schema. The description covers the general purpose and auth but omits return value format, success/failure indicators, and any limitations. For a write tool, this leaves gaps for an agent to understand the full interaction.

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 low (40%). The description adds context by listing inquiry types (mapping to inquiry_type enum) and mentions 'structured inquiry', hinting at structured_payload. But it does not explain contact_email, message length constraints, or listing_id format. Some parameters remain undocumented.

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

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

The description clearly states the verb 'Submit' and resource 'structured inquiry on a listing', and enumerates specific inquiry types (general, showing_request, etc.), distinguishing it from sibling read-only tools like get_listing and search_listings.

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 explicitly requires a registered Trellistate agent API key, providing a clear prerequisite. It also lists examples of inquiry types, implying usage contexts, though it doesn't explicitly contrast with alternatives or state when not to use.

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