cupix-compass

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

The description explains the tool's behavior regarding default saved project usage and retry workflow, but lacks explicit disclosure of whether the operation is read-only, destructive, or has side effects. Without annotations, this gap partially hinders full transparency.

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 well-structured with sections for workflow and arguments, but it is somewhat verbose. Each sentence adds value, though the workflow section could be condensed without losing clarity.

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 tool with two optional parameters and no annotations, the description covers the default behavior, fallback workflow, and return type adequately. The presence of an output schema partially compensates for the lack of return value details, making it sufficiently 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?

Despite 0% schema coverage, the description adds meaningful guidance: both parameters should be omitted by default and used only to override the current project. This clarifies usage beyond the schema's structure, though it could detail expected value formats.

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 tool analyzes Work In Place progress from SiteInsights, covering completion rates, delays, and forecasts. This verb+resource combination is distinct from sibling tools (e.g., compass_list_projects, compass_get_current_project), making its purpose 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?

The description provides explicit workflow instructions: call with no arguments by default, only use compass_list_projects/select if the saved project is missing, and pass explicit arguments only when analyzing a different project. This clearly differentiates when to use this tool versus alternatives.

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?

No annotations are provided, so the description carries full burden. It discloses that the tool returns two specific fields with no side effects. For a simple getter with zero parameters, this is adequate but lacks explicit mention of read-only nature or any potential errors.

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, perfectly concise, front-loaded with action and output. No extraneous 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?

Given zero parameters and presence of an output schema, the description is complete. It succinctly conveys the purpose and return fields. No additional information is necessary for this simple retrieval 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?

There are no parameters (schema coverage 100%), so baseline is 4. The description adds value by specifying what the return values represent (team_domain and facility_key), going beyond the empty 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?

Description clearly states it returns the currently saved team_domain and facility_key for the user. The title further clarifies it checks the focused project. This distinguishes from sibling tools like compass_select_project (which changes focus) and compass_list_projects (which lists all projects).

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 explicit guidance on when to use this tool versus alternatives. While the purpose is clear, there is no mention of when to prefer this over compass_list_projects or compass_select_project, leaving the agent to infer usage context.

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?

No annotations are provided, so the description carries the full burden. It explains the behavior: the parameter fallback logic and the return type (str indicating accessible facilities with keys and names). It also details the workflow after calling the tool, providing transparency about side effects (persisting selection).

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 well-structured with a clear purpose statement, usage guidelines, and a numbered workflow. It is somewhat lengthy but each sentence adds value. Slight opportunity for more conciseness, but overall effective.

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 the simplicity (one optional parameter, no annotations, output schema exists but description only states return type 'str'), the description is quite complete. It covers the tool's role in the workflow, when to use, and what to do after. More detail about the structure of the returned string would improve completeness, but it is adequate.

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 0%, but the description provides rich semantics for the single parameter team_domain: it explains that it is optional, describes the fallback behavior to saved current project, and notes that omitting it may trigger listing teams first. This adds significant meaning beyond the schema.

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

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

The description clearly states 'List construction projects the user can access within a team,' which is a specific verb+resource. It distinguishes from siblings by referencing the workflow and the roles of compass_get_current_project and compass_select_project.

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 'Use this tool ONLY when the user wants to switch project or has no saved current project' and provides a conditional 'If compass_get_current_project returns a saved facility_key, do NOT call this tool.' It also outlines the required workflow steps, including when to call compass_select_project.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool converts natural language to SQL, lists available tables, mentions return format (tab-separated text), and instructs to pass the query as-is. It also explains the server-side resolution of project context. However, it does not explicitly state that the tool is read-only (no destructive actions), which would be beneficial. This warrants a 4 rather than 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?

The description is well-structured with clear sections (including a workflow and table list). It uses bold for emphasis and is front-loaded with the main purpose. While slightly long, every sentence adds value. The structure aids readability for an AI agent. Minor improvement could be shortening the table list, but overall it's concise given the complexity.

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

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

Given the tool's complexity (Text-to-SQL with multiple tables and project context), the description is highly complete. It explains the workflow, when to use parameters, provides a list of available tables, and mentions the return format. Since an output schema exists, detailed return value explanation is unnecessary. The description covers all necessary aspects for an agent to use the tool correctly.

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

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

The input schema has 0% coverage, so the description must compensate. It does so effectively: 'query' is described as a natural language question to be passed as-is; 'team_domain' and 'facility_key' are explained as optional overrides, with the note to omit by default. This adds significant meaning beyond the schema (which only shows string or null). The description also warns against unnecessary calls to obtain these parameters. This is thorough, hence a 4.

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 tool's purpose: 'Query the construction project database using natural language (Text-to-SQL).' It specifies the verb (query), resource (database), and method (natural language). It also distinguishes from the sibling tool 'compass_analyze_work_in_place' by noting that tool is for trade visibility.

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 provides explicit usage guidance: use this tool for natural language queries, and for trade visibility use the alternative. It explains the default workflow (pass only 'query', server resolves team_domain/facility_key) and when to pass explicit parameters. It also advises against unnecessary calls to 'compass_list_projects'. This is comprehensive and 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?

No annotations provided, so the description carries full burden. It explains that the tool searches what is visually seen, returns image viewer links, 3D coordinates, and capture dates. It also describes default behavior (omitting project context) and when to override. No mention of destructive actions or rate limits, but adequate for a read-only search 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?

The description is well-structured with sections: purpose, workflow, date filtering, and parameter list. Every sentence adds value, though it is somewhat lengthy. The workflow section could be slightly more concise, but clarity is prioritized. 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 6 parameters, 1 required, no enums, and an output schema, the description covers all aspects: parameter semantics, usage workflow, and return type. It addresses sibling tool differentiation and project selection flow. The only minor gap is no explanation of the output schema structure, but that is provided separately.

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 0%, so the description must compensate. It does so by explaining each parameter, e.g., query as 'Keywords or phrases describing what to find', team_domain and facility_key as 'Omit by default, pass only to override', and start/end_date with format and usage guidance. This adds critical meaning beyond the schema.

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

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

The title and description clearly state the tool searches 360° site photos by visual content analysis. It distinguishes from sibling tools like compass_query_database (for statistics) and compass_analyze_work_in_place. The verb 'Search' is specific to the resource '360° captures'.

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 provides explicit when-to-use (visual search for hazards, objects, conditions) and when-not-to-use (counts/statistics, use compass_query_database). It includes a detailed workflow for resolving current project, when to call compass_list_projects, and how to handle team_domain/facility_key. This guides the agent on proper invocation.

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?

No annotations are provided, so the description carries full burden. It explains the 'save' action, the clearing behavior, and the conditional requirement for parameters. It does not detail side effects like overwriting or session persistence, but overall it is transparent.

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 concise, well-structured with Args and Returns sections, and front-loaded with the purpose. Every sentence adds value with no fluff or repetition.

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 the tool's simplicity (3 parameters, no annotations, has output schema), the description covers purpose, parameters, and return value adequately. It does not elaborate on error conditions or persistence, but it is sufficiently complete for typical agent use.

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 0%, so the description must explain parameter semantics, which it does well. It describes each parameter's role, the condition that team_domain and facility_key are required unless clear=True, and the clear parameter's effect. This adds significant meaning beyond the schema's types and defaults.

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 tool saves a selection so subsequent calls can omit arguments. It is specific about the verb 'save' and the resource 'focus project', and it implicitly distinguishes from siblings like compass_get_current_project (retrieve) and compass_list_projects (list).

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 (to set a default project) and mentions the clear option, but it does not explicitly contrast with sibling tools or state when not to use. This is good but not fully explicit.

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