skyportal-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation4/5
Most tools target distinct resources (photometry, spectra, classifications, host galaxy, etc.) with clear boundaries. The cluster of generate_* code generation tools and reference tools could confuse, but detailed descriptions and explicit usage guidance mitigate this.
Naming Consistency5/5
All tool names follow a consistent snake_case verb_noun pattern (get_source_*, generate_*, analyze_*, filter_candidates, call_skyportal_api). No mixed conventions or irregular styles.
Tool Count3/5
23 tools is on the heavy side, falling into the borderline range. Several code generation and reference tools could potentially be merged, but each serves a distinct workflow within the astronomical transient domain.
Completeness4/5
The set covers core workflows: source data retrieval, analysis, searching, filtering, and code generation. General API access via call_skyportal_api fills write/update gaps, though dedicated CRUD tools for some entities are absent.
Average 4.1/5 across 23 of 23 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under BSD 3-Clause.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden of behavioral disclosure. It prominently warns that POST, PUT, and DELETE requests permanently modify or delete data and cannot be undone, which is critical for a generic API tool. It does not cover other behaviors like rate limits or authentication, but the write-risk warning is the most essential and well-communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: a one-line purpose followed by a clear warning about write risks. Every sentence earns its place, the most important caution is highlighted with a warning emoji, and the structure is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a generic API call tool with a full schema and output schema, the description covers the main purpose and the critical safety risk. However, it omits any mention of when to use this tool over the many sibling tools, which is a notable gap for overall context. Still, the tool is simple and the description is largely complete for its role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with descriptions for the endpoint, method, data, and params. The description does not add any parameter-specific meaning beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Make an API call to SkyPortal.' It identifies the verb and resource, and the name reinforces the purpose. However, it does not explicitly distinguish this generic caller from the many specialized sibling tools, so it lacks explicit differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this generic API caller versus the dedicated sibling tools (e.g., get_source_photometry). It only provides a write-risk warning, not a 'use when...' explanation or mention of alternatives. This leaves the agent without sufficient decision-making context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full responsibility for behavioral disclosure. It only says 'Convert between' and does not mention auto-detection, the behavior of 'auto' as an output format (returning all formats), or error handling for ambiguous inputs. This leaves gaps in behavioral understanding beyond what the schema already states.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that communicates the core function immediately. Every word contributes value, with no redundancy or filler, making it exceptionally concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple conversion utility, the description plus schema covers the basics, but it omits useful context like the meaning of 'auto' (return all formats) and potential pitfalls of automatic detection. While the output schema may clarify return structure, the description could be more self-sufficient in guiding correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the parameter semantics are already well-documented. The description simply names the same formats that appear in the schema's value examples, adding no additional meaning or examples. Thus, the baseline of 3 applies: the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Convert between MJD, JD, ISO datetime, and Unix timestamps' with a specific verb and named resources. It distinguishes itself from all sibling tools, which are focused on source data and analysis, leaving no ambiguity about its unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit alternative tools exist among the siblings for time conversion, so the description's clear scope is sufficient to imply when to use it. It could be improved by suggesting typical scenarios (e.g., converting time formats before querying other APIs), but the context is fully clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 the return content (name, probability, who made classification), which is useful. However, it does not mention potential edge cases, error behavior, or any side effects, though as a read operation this is less critical. The description adds some behavioral context but not extensive detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with the main purpose front-loaded. It avoids redundancy and fluff, and every sentence contributes to understanding the tool's function and output.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema exists), the description is complete enough: it states the purpose and the key components of the response. It does not need to explain return structure since the output schema likely covers that. Minor gap: no mention of empty results or authorization, but not essential for this type of tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema's description for source_name is already detailed, including examples and accepted identifier forms. The tool description adds no additional parameter semantics beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and resource 'classifications for a source', which distinguishes it from sibling tools like get_source_photometry or get_source_spectra. It also specifies what is returned (classification name, probability, and classifier), adding precision beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need classifications for a source) but does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. The context is clear, but there is no direct guidance compared to other get_source_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It discloses that the result depends on a host association and lists specific data returned (angular separation, physical distance). It does not explicitly state read-only status, error handling, or what happens when no association exists, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, front-loaded with the main purpose, and every sentence adds context (function, return content, association condition). No redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and a simple single-parameter operation, the description adequately covers the tool's conditional behavior and scope. It lacks explicit error-case or permission info but is sufficient for basic selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter source_name is fully described in the schema (100% coverage), so the description adds no additional parameter semantics. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieve') and resource ('host galaxy information'), clearly distinguishing it from sibling get_source_* tools that return other data types. It further specifies the returned content (angular separation, physical distance).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when host galaxy association is needed, and the conditional 'If a host association exists' gives some context. However, it does not explicitly contrast with alternatives or provide when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It does state that the tool 'generates Python code' rather than executing the search, which is useful. However, it does not clarify any requirements, potential failures, rate limits, or that the code must be run separately. This is adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening, an explanation, and a dedicated 'Use Case' section. It is not overly long, though the first sentence is somewhat repetitive with the tool name. Overall, it is efficient and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only two parameters, one required, and rich schema descriptions, the contextual information is sufficient. The use case adds valuable guidance, and the presence of an output schema reduces the need to explain return values. The description could mention the format of the generated code, but this is not a major gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with detailed parameter descriptions and examples for both coordinates and radius. The description adds little beyond the schema, merely restating that the search is 'within a radius of specified sky coordinates.' Given the high schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Generate code to perform ZTF cone searches at multiple positions.' It clearly differentiates from sibling tools like search_sources_near_position by emphasizing code generation rather than execution. The mention of 'multiple positions' also adds scope specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use Case' section explicitly states when to use the tool: when you have a list of coordinates and want to find ZTF detections nearby. It provides practical context such as catalog cross-matching and coverage checks. However, it does not explicitly mention alternatives or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the default behavior returns a summary to avoid token overflow, and that verbose=True or format='csv' retrieves full data. This adds behavioral context beyond the schema, warning about potential large responses. However, it does not mention what happens for missing sources or any access restrictions, which would improve transparency given no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: one for purpose and one for behavior. It is front-loaded, efficient, and contains no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose and default behavior, and an output schema exists to define return values. However, it omits mention of format='json' as another way to get full data, potentially creating confusion with the schema. It also lacks any information on edge cases such as no spectra found or performance implications for large sources.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for all three parameters at 100% coverage. The description adds rationale for the default format ('to avoid token overflow') and reinforces the effect of verbose and csv, but it does not significantly add to the schema's existing parameter explanations. The mention of 'full spectral data' clarifies the purpose but not novel semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve spectra for a source' with a specific verb and resource, distinguishing it from sibling tools like get_source_photometry or get_source_classifications. It is unambiguous about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, nor does it mention any excluding conditions. Usage is implied by the tool name and purpose, but no guidance is given for choosing this over related spectral data tools. The mention of token overflow provides some context but not usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosure. It does mention that it 'Generates CSV data file + Jupyter notebook,' which is a behavioral side effect. However, it does not explicitly state whether the operation is read-only or if it modifies source data, nor does it disclose any potential side effects like API calls or runtime. This leaves some ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, using bullet points to separate the two computational methods. It front-loads the primary purpose and keeps additional details compact. Every sentence adds value without redundancy, making it easy for an agent to quickly grasp core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, one required, and an output schema), the description adequately covers the core workflow: calculating curves, generating CSV and notebook. It does not explain the meaning of 'color at peak brightness' or how peak brightness is determined, but the output schema likely covers return details. Overall, it is sufficient for a standard analysis tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter already having a detailed description. The tool description adds minimal parameter-specific meaning, only referencing band1 and band2 in the context of color curves. Since the schema fully documents parameters and defaults, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Analyze color evolution and color at peak brightness.' It specifies the resource (color curves from band1 - band2) and distinguishes itself from sibling tools like analyze_light_curve by focusing on color rather than light curves. The mention of both matched and interpolated methods further clarifies its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear context for use—when you need color evolution analysis with two methods and artifact generation. However, it does not explicitly name alternatives or state when not to use this tool. The absence of exclusions is balanced by the specificity of the purpose, making the usage intent obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool generates code (rather than directly downloading) and explains what alert packets contain. However, it does not mention prerequisites, limitations, output format, or any potential side effects, leaving some behavioral aspects unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the main purpose, and uses a clear 'Use Case' bolded section. Every sentence adds value, and the structure makes it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 params, output schema present), the description provides enough context: clear purpose, detailed explanation of alert packets, and a specific use case. It does not explain return values, but the output schema handles that, so the description is complete enough for a code-generation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 does not add explicit parameter-level meaning beyond the schema; it only implies the 'sources' parameter via 'multiple sources' and mentions cutouts in the context of alert packet contents, which indirectly relates to 'with_cutouts'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Generate code to download ZTF alert packets for multiple sources.' It clearly distinguishes this tool from sibling code-generation tools (e.g., generate_bulk_lightcurve_code) by focusing on raw alert packets and explicitly describing their contents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use Case' line states when to use this tool ('when you need complete alert history...alert-level data that isn't available in forced photometry'). This provides clear context and an implicit alternative (forced photometry), though it does not explicitly name sibling tools 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It discloses that the tool generates browsing URLs and that source_id auto-resolves coordinates. However, it does not mention authentication requirements (which appear in the schema), rate limits, or which surveys are considered 'common.' These gaps prevent a higher score, though the read-only nature is implied by 'Get URLs.'
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences: the first front-loads the purpose, the second gives input guidance. There is no redundant or extraneous content, making it concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, a rich output schema, and well-described parameters, the description covers the essential input modes and purpose. It could name specific surveys or note that multiple URLs are returned, but the output schema likely handles return details. Overall, it is adequate for a straightforward retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage of parameter descriptions, including the mutual exclusivity of ra/dec versus source_id and the auto-resolution behavior. The description's sentence about providing either ra/dec or source_id largely duplicates schema content, adding minimal new semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'Get URLs to browse a sky position in common astronomical surveys.' This distinguishes it from sibling tools focused on photometry, spectra, classifications, and other data retrieval. It also specifies two input modes (ra/dec or source_id).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly guides the user to provide either ra/dec coordinates or a source_id, and explains that source_id auto-resolves coordinates from SkyPortal. However, it does not contrast this tool with alternatives like search_sources_near_position or get_source_photometry, so a user may not know when to prefer this tool over those.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It reveals that this is query-time filtering (not alert-time), mandates user confirmation before execution, and says to offer the filter configuration JSON after results. These are meaningful behavioral disclosures beyond what a schema would indicate, though it could also mention pagination or return format (but output schema exists).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear paragraphs and bolded 'IMPORTANT' sections, making it scannable. The parameter-validation examples add length but are valuable for guiding the required user interaction. It is slightly longer than strictly necessary, but every sentence contributes behavioral or usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (13 parameters, no required fields) and the presence of an output schema, the description adequately covers the tool's role, the mandatory user-confirmation workflow, and post-result actions. It does not explain return values, but the output schema handles that. The description is sufficiently complete for an agent to understand when and how to invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already provides comprehensive parameter documentation. The tool description adds some examples within the parameter-validation section (e.g., 'braai score > 0.9', 'sgScore < 0.3'), but these do not expand on the schema's parameter semantics. The baseline of 3 is appropriate because the schema does the heavy lifting, though the examples reinforce usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Search for candidates matching specific criteria on the scanning page,' which clearly states the verb (search), resource (candidates), and scope (scanning page). It further distinguishes itself by clarifying 'query-time filtering of existing candidates (not alert-time filtering),' which separates it from similar tools. This is a specific and clear purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use the tool: 'Use this to search the scanning page for candidates matching specific properties.' It also provides procedural guidance, such as 'Before executing this tool, ALWAYS confirm with the user that the filter parameters are reasonable.' However, it does not explicitly mention alternative tools or when NOT to use it, so it misses the full 'when/alternatives' guidance for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 states the tool 'generates code' but does not explicitly state that it is read-only or that it only returns code without executing it. It also does not disclose potential prerequisites like authentication or external dependencies. The description is not misleading, but it could be more explicit about the nature of the output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using three short sentences plus a bolded use case. It is front-loaded with the main purpose and wastes no words. Every sentence adds meaningful context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, output schema present) and the clear description, nothing essential is missing. It explains what the tool does, when to use it, and the parameters are fully documented in the schema. It is complete for its intended function.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers 100% of the parameters, with clear descriptions for both 'field_id' (ZTF field ID 1-1895) and 'ccd_id' (optional CCD ID to highlight, with default behavior). The description adds no additional parameter semantics, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Generate code to visualize ZTF field and CCD coverage.' It specifies the exact resource (ZTF field and CCD) and the action (generate code to create sky maps). This is easily distinguished from sibling tools that generate other types of code (light curves, cone searches, alerts).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit use case: 'When you need to visualize which parts of the sky are covered by specific ZTF fields or CCDs.' It also explains the utility ('understanding coverage and planning observations'). However, it does not mention alternatives or when not to use this tool, which would make it a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It states the tool 'Returns a reference of available API endpoints...' and recommends calling once, which implies a safe, read-only operation with a one-time load into context. It does not explicitly mention lack of side effects, but that is strongly implied by the reference nature. It adds context about the recommended usage pattern.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, each serving a purpose: identifying the tool, describing the content, and providing usage guidance. It is front-loaded and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description is quite complete: it identifies the resource, the content of the reference, and the recommended usage. It does not cover the distinction from the sibling 'get_tools_quick_reference', so a small contextual gap remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes no parameters, as shown by the empty input schema. According to the rubric, zero parameters gives a baseline score of 4. The description adds no parameter-specific details, but none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a reference for the SkyPortal API, with a specific verb ('Get') and resource ('API quick reference guide'). It explains what the reference contains (endpoints, required parameters, usage patterns). However, it does not explicitly distinguish itself from the sibling 'get_tools_quick_reference' tool, so it falls 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The instruction 'Call once to load into context as needed' provides clear context for when/how to use the tool, and implies a one-time usage pattern. However, it does not explicitly state when to use this tool versus the related 'get_tools_quick_reference' or any alternative, nor does it provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It states the output format (CSV), that it returns all photometry points, and details the column structure for both mag and flux formats. This adds meaningful context beyond the schema, though it does not mention error handling or performance limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening sentence followed by column lists for each format. It is concise but includes necessary detail about output formats. The length is appropriate and front-loaded, avoiding wasteful repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 params, 1 required) and the presence of an output schema (columns), the description is complete in explaining the output and basic behavior. It lacks explicit usage guidance or edge-case behavior, but for a retrieval tool this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 adds value by explaining how the format parameter affects the output columns (mag vs flux), and clarifies the default values. It also enumerates the exact returned columns, which enriches understanding of the filters and magsys parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves photometry for a source as a CSV table, with specific verb and resource. It lists exact columns for mag and flux formats, making it distinct from sibling tools like get_source_spectra or get_source_classifications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving photometry but does not explicitly compare with alternatives or state when to use this versus other source tools. It lacks exclusions or guidance on when not to use it, so it's only implied by the tool's name and purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It adds the key behavior of returning sources within a radius and the auto-resolution of coordinates from a source_id. However, it does not disclose authentication requirements (other than in schema), rate limits, or behavior when no parameters are provided, which limits transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three sentences) but has minor redundancy: 'Search for sources near a position' is repeated in 'Finds all sources within a specified radius.' Overall it is well-structured and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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, usage context, and key input alternatives. An output schema exists, so not explaining return values is acceptable. It could mention edge cases (e.g., if neither ra/dec nor source_id is provided), but the description is reasonably complete for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 adds value by explaining the either/or relationship between ra/dec and source_id, helping the agent understand valid input combinations. This goes beyond the individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Search for sources in SkyPortal near a position') and explains it as a cone search. It distinguishes from siblings like generate_cone_search_code by focusing on the actual search operation, not code generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear use cases: 'checking if a source already exists... or finding nearby sources.' It does not explicitly mention alternatives or when not to use, but the context is sufficient for an agent to understand appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so description must carry the burden. It transparently discloses that the tool only generates code (not downloads directly), requires a Fritz API token, and gives setup instructions. It also lists the data types (photometry, spectra, metadata). However, it does not detail the generated code's output format or execution side effects, leaving some behavioral aspects implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: main verb in first sentence, then a clear use case, and a required-auth note. Every section adds value, and formatting with bold labels improves scannability without unnecessary prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-param tool with an output schema and clear purpose, the description is largely sufficient: it explains what is generated, why/when to use, and the prerequisite. It lacks explicit comparisons to sibling tools like generate_bulk_lightcurve_code, but the use case and scope are enough for an agent to select it correctly in most contexts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with descriptions for both parameters (sources with example, include_spectra with default). The description adds minor context about 'multiple sources' and 'photometry, spectra, and metadata' but does not enhance parameter understanding beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+object: 'Generate code to bulk query Fritz/SkyPortal for multiple sources.' It specifies the resource (Fritz/SkyPortal), the action (generate code), and scope (multiple sources), and further clarifies it produces code for downloading photometry, spectra, and metadata, distinguishing it from sibling tools like generate_bulk_lightcurve_code.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use Case' section explicitly states when to use: 'When you need to download data products from Fritz for many sources at once (faster than individual API calls).' This implies the alternative of individual API calls, but does not name specific sibling tools or exclusions (e.g., single sources or lightcurve-only needs), making it clear but not fully prescriptive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well: it states the tool 'Returns a summary' and defines what comments and annotations are. It does not mention potential side effects or prerequisites, but the retrieval nature is clear and the return semantics are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: the first sentence states the purpose, the second describes the output type, and the third clarifies the difference between comments and annotations. No word is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with a fully described schema and an output schema, the description covers the essential behavioral aspects. It explains the return content and the nature of the data, making it self-sufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter source_name is already well-described in the schema. The description adds little beyond the schema, only referring generically to 'a source'. Thus the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieve') and resource ('comments and annotations for a source'), clearly distinguishing it from siblings like get_source_photometry or get_source_spectra. It also clarifies the difference between comments and annotations, which helps disambiguate the tool's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates the tool returns user comments and system/ML annotations, which provides enough context for an agent to decide when to use it. However, it does not explicitly mention alternatives or exclusions (e.g., when to use get_source_classifications instead), so it falls short of full explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It reveals the output is a 'comprehensive list' and suggests calling once, implying potential cost/size, but does not detail behavioral aspects like response size, latency, or side effects beyond that hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the purpose, no superfluous details. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with an output schema, the description is sufficient: it states what is returned, how it is organized, and when to call it. No gaps that would prevent correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100%. The baseline for 0 params is 4, and the description does not need to add parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves a quick reference guide for MCP tools, listing content categories and examples. It distinguishes itself from the sibling tool get_api_quick_reference by focusing on MCP tools rather than the API.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It says 'Call once to load into context when needed,' providing clear usage context but no explicit alternatives or exclusions. This is adequate but could be more explicit about when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 this is an alert-time filter running on the Kowalski backend, that it produces MongoDB aggregation pipeline JSON compatible with Fritz, and that it is not a query-time filter. It also explains the workflow for importing/generating filters, which clarifies that it generates JSON rather than directly modifying Fritz. The description does not mention any destructive side effects, but none are implied, and the tool appears non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with clear headers, bullet points, and bolding for important points. Every section adds value, from the core purpose to the recommended workflow and alternatives. It is not overly verbose given the complexity of the tool and the need to explain the alert-time vs query-time distinction.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex (generates MongoDB pipeline JSON), and the description provides comprehensive context: what the tool does, when to use it, how it relates to siblings, and recommended workflows. The presence of an output schema and fully described parameters means the description does not need to explain return values or parameter syntax. The description is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage of all parameters with detailed descriptions and defaults. The tool description adds context about the overall filter purpose but does not significantly enhance the parameter-level semantics beyond what the schema provides. Per the rubric, with high schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Generate MongoDB filter JSON for a watchlist to monitor specific coordinates.' It also distinguishes itself from sibling tools by explicitly contrasting with query-time filtering using filter_candidates, making its unique purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: it is an alert-time filter that runs on every incoming alert, and it explicitly differentiates itself from query-time filtering with filter_candidates. It also offers two recommended workflows (MongoDB Compass and direct use), giving the agent clear context for both when and how to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description takes on the transparency burden. It clearly states side effects and outputs: 'Generates CSV data file + Jupyter notebook with interactive Plotly plots plus editable analysis code cells.' It also explains behavior for incomplete light curves and the baseline_threshold parameter semantics. However, it doesn't explicitly state that it is a read-only analysis or mention any system-level effects, leaving a small gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a strong lead sentence, a clear list of computed properties, a bulleted summary of edge-case handling, and explicit output details. Each section earns its place without redundancy, and the overall length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and the presence of an output schema, the description covers all necessary selection and invocation context: what it does, how parameters affect output, edge cases, and what artifacts it produces. An agent can confidently choose this tool and understand its behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema by linking parameters to analysis behavior, such as 'for each requested photometric band' and explaining baseline_threshold in the main description. It also gives concrete filter string examples, which help agents form correct values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Analyze light curve evolution for multiple photometric bands,' using a specific verb and resource. It clearly states the computed quantities (rise time, fade time, duration, pre-peak variability) and differentiates from siblings like get_source_photometry (raw photometry) and analyze_color_evolution (color analysis).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool by explaining how incomplete light curves are handled (still rising, still fading, returned to baseline) and what output formats are available. It does not explicitly name alternative tools or exclusion criteria, but the use cases are well implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It discloses that the tool returns documentation rather than data, explains the distinction between query-time filtering and alert-time filters, and notes that it helps determine what is filterable via API queries vs custom computation. This goes beyond the minimal structural information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, each adding value: what it does, what it returns, when to use it, and a critical exclusion. It is front-loaded with the primary purpose and avoids unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an output schema, the description is complete: it clarifies the tool's role as a reference, enumerates the kinds of filters covered, and explicitly differentiates from alert-time MongoDB filters. This is enough for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. No parameter documentation is needed. The description instead focuses on the tool's output and usage context, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that this tool returns a reference/documentation for filtering candidates and sources on Fritz/SkyPortal. It specifies the verb "Get" and the resource "reference for filtering candidates and sources," distinguishing it from actual filtering tools like filter_candidates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to call it ('when a user asks to filter, search, or scan for specific types of transients') and provides a when-not caveat ('NOT for creating alert-time MongoDB filters'). It does not name a specific alternative tool for the alert-time case, but the guidance is otherwise clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosure. It discloses the tool's behavior thoroughly: creates a notebook, downloads alert photometry, uses multiprocessing, saves to CSV, and creates Plotly plots. It also explicitly states it does NOT download forced photometry, a key limitation, and mentions the required setup. This goes beyond a basic action statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a clear opening sentence, a detailed explanation, and a bolded note highlighting the key limitation. It is somewhat longer than minimal but every sentence adds value, including the note about forced photometry and the setup snippet. The use of bold and code formatting improves readability without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex (generates a notebook with multiple features), but the description covers all essential context: what it does, what it doesn't do, requirements, and setup. Since an output schema exists, return-value details are not needed. The description leaves no major gaps for an agent to misunderstand when to use this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for all three parameters (filters, sources, include_plots), so baseline is 3. The description does not add additional parameter-level context beyond what the schema already provides, but it gives general workflow context that indirectly helps understand how parameters are used. No contradiction or missing param info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a Jupyter notebook for bulk downloading ZTF light curves from Fritz. The verb 'Generate' plus the specific resource (notebook) and purpose (bulk download alert photometry) distinguish it from sibling tools. The explicit focus on alert vs forced photometry further differentiates it from alternative data sources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-to-use guidance: use for bulk alert photometry downloads. It explicitly states when NOT to use it (for forced photometry) and recommends the IRSA ZTF forced photometry service as an alternative. It also lists prerequisites (ztfquery + API token) and setup instructions, giving the agent sufficient context to decide when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses that the tool aggregates and formats all relevant data, including source ID, photometry, classification, and host galaxy. It also states that it accepts any source identifier. It does not mention auth or read-only status, but for a summary tool the behavior is sufficiently clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat long but well-structured with bullet points and a dedicated usage section. Every section adds value: the summary purpose, data list, accepted identifiers, and when-to-use guidance. No redundant filler; the length is justified by the need to differentiate from many sibling tools.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's full scope—what data it retrieves, why it is the preferred choice, and when to use it. Given that an output schema exists, return values need not be detailed. The description is complete for a complex aggregating tool with one parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the source_name parameter, but the description adds valuable context by listing accepted identifier types (SkyPortal obj_id, ZTF name, TNS name) with examples. This goes beyond what the schema provides and clarifies acceptable input formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates a complete TNS/AstroNote report and lists specific data categories, distinguishing it from sibling tools like get_source_photometry and get_source_spectra. The verb 'generate' plus the resource 'TNS/AstroNote report' makes the purpose specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides a 'When to use' section with exact user intents (e.g., 'create/generate/write TNS report') and explicit 'Do NOT' guidance to avoid using multiple separate tools. This strongly steers tool selection and prevents misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 source_id auto-resolves RA/Dec from SkyPortal, that source_id requires authentication (also in schema), and warns about the alternative endpoint's PDF output. This adds meaningful behavioral context, though it doesn't cover all edge cases or output details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: three short paragraphs that front-load the purpose, then give explicit usage directives, and finally summarize input modes. No unnecessary repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and parameter descriptions are thorough, the description covers the essential context: what it does, when to use it, what not to use, and how to provide inputs. The only omission (detailed return format) is properly deferred to the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The main description adds semantic value by clarifying the either/or relationship between source_id and ra/dec, which is not explicitly stated in the schema, and by emphasizing the 'all telescopes' option.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Compute' with the resource 'observing windows' and the scope 'from specified telescopes', clearly distinguishing it from sibling tools like photometry or spectra. It also states 'USE THIS TOOL for all observability questions', which reinforces its unique role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'USE THIS TOOL for all observability questions' and instructs against using the /api/sources/{id}/observability endpoint, explaining that it returns an unparsable PDF. It also provides clear input-mode guidance: provide either source_id or ra/dec.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![skyportal-mcp MCP server](https://glama.ai/mcp/servers/AnastasiaKWei/skyportal-mcp/badges/card.svg)](https://glama.ai/mcp/servers/AnastasiaKWei/skyportal-mcp)

Score Badge

Copy to your README.md:

[![skyportal-mcp MCP server](https://glama.ai/mcp/servers/AnastasiaKWei/skyportal-mcp/badges/score.svg)](https://glama.ai/mcp/servers/AnastasiaKWei/skyportal-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/AnastasiaKWei/skyportal-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server