cupix-compass

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses that user_intent is analytics-only and does not affect results, that team_domain/facility_key default to the saved project, and that the tool will signal missing current project. These trait disclosures add valuable behavioral context not captured in 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?

The description is well-structured with clear sections (overview, workflow, args, returns). Every sentence serves a purpose—explaining behavior, usage, or parameters—and avoids redundancy. The formatting improves readability despite the length.

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 description covers the tool's purpose, argument semantics, default behavior, interaction with sibling tools, and return type. Given the existing output schema and annotations, the description is sufficiently complete for an agent to select and invoke the tool correctly without missing critical context.

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 thoroughly explains each parameter: team_domain and facility_key are optional overrides, user_intent is passed verbatim but only for analytics. However, it calls user_intent 'REQUIRED' while the schema shows a default and does not list it as required, creating a potential contradiction that could mislead an agent.

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 (Analyze), the specific resource (Work In Place progress from SiteInsights), and the outputs (completion rates, delays, forecasts, progress report). It distinguishes itself from siblings like ask-about-project-data by emphasizing analytical report generation rather than general project Q&A.

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 workflow section provides explicit when-to-use guidance: default to no arguments relying on the saved project, explicitly avoid calling list-my-projects unless the project is missing, and only pass overrides when analyzing a different project. It names sibling tools and exact steps for recovery, which is excellent 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?

The description goes well beyond the readOnlyHint/openWorldHint annotations by disclosing SQL conversion, server-side current-project resolution, result row caps at 200, cursor-based pagination, and the fact that user_intent is used only for analytics and does not affect results. This gives the agent a clear model of how the tool behaves.

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 longer than average but is well-structured: a crisp purpose sentence, an explicit sibling alternative, a bulleted workflow, an available-tables catalog, and a compact Args section. Every sentence earns its place, and the content is front-loaded with the most important usage guidance.

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 complex 7-parameter tool with no schema descriptions, the description is unusually complete. It covers the full invocation workflow, parameter semantics, available database tables, pagination/limit behavior, and return format, leaving no significant gaps for correct 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?

Even though schema description coverage is 0%, the description explains every parameter: query must be passed as-is, team_domain/facility_key default to the saved project, user_intent must be the original verbatim request, scope searches within a previous result, limit caps at 200 rows, and cursor enables paging. This fully compensates for the sparse 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 identifies the tool as a natural-language Text-to-SQL query tool over the project database, listing retrievable data types such as captures, annotations, progress metrics, and schedules. It distinguishes itself from siblings by explicitly directing trade-visibility questions to analyze-progress-and-forecasts.

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 gives explicit usage guidance: use this tool for general project-data queries, and use analyze-progress-and-forecasts instead for trade visibility. It also details a concrete workflow—call with only query by default, avoid redundant list-my-projects calls, recover via list-my-projects → set-focus-project when no project is set, and pass team_domain/facility_key only to override the current 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?

Annotations already declare readOnlyHint=true, so the description adds useful context by specifying the exact return fields (team_domain and facility_key) and that it is for 'this user'. No contradiction exists, and the behavior is adequately transparent for a simple read operation.

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 a single sentence, starts directly with the verb 'Return', and contains no unnecessary words. It is concise, front-loaded, and appropriately sized for the tool's simplicity.

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

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

For a simple read-only getter, the description covers the core functionality and return fields. The output schema exists to detail return structure. However, the unexplained 'user_intent' parameter and lack of mention of behavior when no project is set create minor gaps, preventing a perfect score.

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 one optional parameter 'user_intent' with no description, and schema description coverage is 0%. The tool description does not mention this parameter at all, leaving its purpose and expected values entirely unexplained. Since the description must compensate for low schema coverage, this is a significant gap.

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 uses the specific verb 'Return' and identifies the exact resources ('currently saved team_domain and facility_key'), clearly stating the tool reads the current project context. This distinguishes it from siblings like set-focus-project (which modifies the project) and list-my-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?

The title 'See which project the conversation is currently focused on' communicates a clear use case, and the description reinforces it by specifying the saved fields. However, it does not explicitly name alternatives or state when not to use this tool, relying on context from sibling tools.

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?

Discloses a key behavioral trait beyond annotations: the runtime uses pano camera coverage, causing uncertain cases to be returned as INDETERMINATE rather than guessed. This adds significant transparency about result semantics, going beyond the readOnlyHint annotation and helping the agent set expectations.

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 sentences, each earning its place: purpose, follow-up guidance, and behavioral caveat. No fluff or redundancy, perfectly concise and well-structured.

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 description provides enough for basic usage but is incomplete for a tool with 13 parameters. It covers the core concept and important caveat, and the output schema exists, but the parameter richness is not fully addressed. The lack of parameter descriptions means the agent may be uncertain about advanced filtering options, reducing overall completeness.

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?

With 13 parameters and zero schema descriptions, the description only covers a few: baseline_date and comparison_date (implied by 'two dates'), level_ids and min_confidence ('level or confidence filters'). Many parameters like query, statuses, polygon, timezone, team_domain, facility_key, minimum_level_number, user_intent, and limit are not explained, leaving a significant semantic gap.

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 compares findings between two dates for QA/QC questions, listing specific delta states (added, resolved, unchanged, moved). It distinguishes from siblings like analyze-progress-and-forecasts by focusing on change detection between captures, making the purpose 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?

Provides explicit when-to-use context ('Use for QA/QC questions') and actionable advice for follow-up calls (reuse prior dates, add level/confidence filters). It lacks explicit mention of alternatives or when not to use, but the context is clear enough to guide selection.

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 only state readOnlyHint and openWorldHint. The description adds important behavioral details: team_domain fallback behavior, user_intent being analytics-only, and the required multi-step workflow. It also clarifies the return type as a string of accessible facilities, which is beyond 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?

The description is well-structured with a bold usage rule, a clear numbered workflow, and separate Arg explanations. Every sentence adds practical value; the length is justified by the complex workflow required.

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 description is complete for this tool's context: it explains when to use, prerequisites, workflow steps, parameter behavior, fallback logic, and return value. The presence of an output schema reduces the need but the description still covers the essential context thoroughly.

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%, but the description fully documents both parameters. It explains team_domain is optional and what happens if omitted, and that user_intent is REQUIRED and passed verbatim for analytics only—significantly adding meaning beyond the bare schema properties.

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 lists construction projects the user can access within a team. It distinguishes itself from siblings by specifying when to use it ('ONLY when the user wants to switch project or has no saved current project') and by contrasting with check-current-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 gives explicit when-to-use and when-not-to-use guidance, including an alternative: 'If check-current-project returns a saved facility_key, do NOT call this tool — call the analysis tool directly.' It also provides a numbered workflow for presentation, selection, and persistence via set-focus-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?

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds valuable workflow behavior: server auto-resolves project context from the saved project, when to retry with project setup, and that user_intent is analytics-only and does not affect results. It doesn't describe pagination/return semantics in depth, but the output schema covers that, and the behavioral notes exceed what annotations provide.

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 longer than typical but every section earns its place: purpose, workflow, date filtering, and per-argument notes. Markdown structure (WORKFLOW, Date filtering, Args) makes it scannable. Slightly verbose with the Args section duplicating some schema field names, but the behavioral notes justify the length.

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?

This is a complex tool (9 params, nested scope object with pano list, pagination via cursor, cross-tool workflow). The description addresses the multi-step fallback workflow, project context resolution, and date handling comprehensively. The output schema covers the return structure. Minor gap: the cursor pagination interaction could be spelled out more explicitly, but overall completeness is strong for the complexity.

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%, so the description must compensate for all 9 parameters, and it does: every param gets an inline explanation (query='keywords describing what to find', team_domain/facility_key='omit by default, override current project', user_intent='REQUIRED...does not affect results', limit='default 10', date params='YYYY-MM-DD, omit if no date context', scope='previous result identity', cursor='next page'). This fully compensates for the 0% 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 has a very specific verb+resource ('Search 360° captures by visual content analysis') and clearly distinguishes from siblings by explicitly naming what it does NOT do (capture counts/statistics → ask-about-project-data). It enumerates the exact content types searched (safety hazards, quality issues, work types, objects, equipment, materials, conditions).

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?

Provides an explicit WORKFLOW section detailing default usage (query only), when to override with team_domain/facility_key, when to run list-my-projects → set-focus-project (only when current project is missing), and precise date-filtering guidance (only when user mentions dates, YYYY-MM-DD format). The exclusion of the stats use case with a named alternative is exemplary.

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 explicitly says it will 'Save' and, with clear:true, 'delete the stored selection,' indicating a state-modifying write operation. This directly contradicts the annotation 'readOnlyHint: true,' which classifies the tool as read-only. This is an annotation 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?

The description is well-structured, front-loaded with the core purpose, and then uses a compact Args/Returns format. Every sentence adds meaningful information, such as required conditions and the return value, 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?

For a stateful tool with 4 parameters, the description covers all parameter semantics, the clear behavior, and the return value, making it usable without external documentation. It loses one point for not mentioning alternative tools or addressing the annotation contradiction, leaving some contextual 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?

The schema coverage is 0%, but the description fully compensates by explaining each parameter: team_domain and facility_key are required unless clear=true, clear deletes the stored selection and ignores other args, and user_intent is required for analytics and does not affect results.

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 starts with a precise verb and object: 'Save the user's current team and project,' which clearly states what the tool does. It also differentiates this tool from the sibling 'check-current-project' (which likely only reads) by emphasizing the action of saving for future calls.

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 gives clear usage context: it is used so that 'subsequent tool calls can omit the team_domain / facility_key arguments.' However, it does not explicitly state when not to use it or name an alternative like 'check-current-project' for verifying the current focus.

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