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

Annotations already declare readOnlyHint and openWorldHint, so the description is not burdened with safety disclosure. It adds context about the authenticated scope, paginated results, and ordering by last update, which exceeds the structured annotation information. No side effects or rate-limit warnings are needed for an obviously read-only list 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 two sentences and contains no filler. It front-loads the core action and then covers filtering and result behavior, with every sentence contributing useful information.

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

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

For a simple read-only listing tool, the description covers the resource, auth scope, optional filtering, pagination, and ordering, and the output schema supplies return structure. It does not explicitly state that omitting the filter returns all data sources, though the schema property mentions it. The enum/value mismatch in the schema is a small gap in 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?

Schema description coverage is only 33%, and the main description says only 'Optionally filter by data source type(s)' without detailing page or limit. More seriously, the schema property description for data_source_types lists values like 'pdf_upload', 'open_api', and 'custom_webcrawler' that do not match the actual enum values ('file_upload', 'openAPI', 'custom_website_crawler'), which could mislead an agent. The description does not compensate for this inconsistency.

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

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

The description opens with a specific verb and resource: 'List data sources for the authenticated application.' It also states optional filtering and pagination/ordering, making its scope unambiguous. While it does not name a sibling tool, no sibling overlaps with this resource's list operation, so distinction is clear.

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 establishes when to use the tool: to list the authenticated app's data sources, optionally filtered by type. It does not mention alternatives or exclusions, but the sibling set contains update_data_source and analytics endpoints that serve different purposes, so the context is sufficient.

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